Use definitions and references within the same route

[AustinGil]

I have a route that returns an object with a few properties. Each of these properties is another object with a few props. All of these nested objects follow the same schema, it's just the values that change, so I thought a definition and reference would be the best way to represent them.

https://cswr.github.io/JsonSchema/spec/definitions_references/

However, when I tried to implement them the way described in the spec, it did not work. The only example I see of refs in this project's docs are if you use oapi.component. I didn't think that was a great approach for my use case as these are not really global objects I want to make available.

[wesleytodd]

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.

[nruotsal]

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?

[wesleytodd]

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?