Use definitions and references within the same route about express-openapi HOT 3 OPEN

Interesting, so I am not sure that I understand the concern about them being global. All the .component api does is add a spec compliant component section to the doc, so it is "global" in the sense that any other part of the doc can reference it ($ref), but that is just how the spec works.

The api we expose is just a shorthand/helper so you dont have to write out the rather unpleasant format. So when you "use" the component you defined it just returns the ref: https://github.com/wesleytodd/express-openapi/blob/main/index.js#L94

Am I missing something about what you are asking? If so, please help me better understand.

from express-openapi.

I have a similar issue. I'm generating TypeScript types from JSON Schema files with https://github.com/bcherny/json-schema-to-typescript tool.

I want to use those JSON Schemas to generate OpenAPI docs like this

import MySchema from 'schemas/MySchema.json';

openapi.component('schemas', 'MySchema', MySchema);

And in MySchema.json I have something like this

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "SubSchema": {
      "type": "object",
      "properties": {
        "someValue": {
          "type": "string"
        }
      }
    }
  },
  "title": "MySchema",
  "type": "object",
  "properties": {
    "someArray": {
      "type": "array",
      "items": { "$ref": "#/definitions/SubSchema" }
    }
  }
}

But this does not work with express-openapi. Only way I got it working was to move SubSchema to its own json file and change $ref to { "$ref": "#/components/schemas/SubSchema" }. Then change code to

import MySchema from 'schemas/MySchema.json';
import SubSchema from 'schemas/SubSchema.json';

openapi.component('schemas', 'SubSchema', SubSchema);
openapi.component('schemas', 'MySchema', MySchema);

After that TypeScript types generation fails because it can't find SubSchema anymore. Would it be possible to add support for definitions and references inside same JSON Schema file?

from express-openapi.

Hey @nruotsal, I think this is a different request. I do not see a clear way to know what to merge from a call to .component with the parent doc. Additionally, I think that you can achieve what you want with two calls into this package, so am not sure we would want to change the api to accommodate this particular case unless you can elaborate on the goal. If you think there is a strong argument for this, can you open a new issue and make the case for supporting this?

from express-openapi.