Add support for $ref in API definitions

[line-o]

Given an API definition that includes the following user schema in components

"components": {
  "schemas": {
    "user": {
      "properties": {
        "id": { "type": "integer" },
        "name": { "type": "string" }
      }
    }
  }
}

The above user schema must be referencable by "$ref": "#/components/schemas/user" like in the response definition below:

"responses": {
  "200": {
    "description": "The response",
    "schema": {
      "$ref": "#/components/schemas/user" 
    }
  }
}

Components spec: https://oai.github.io/Documentation/specification-components.html

At least, following objects must be supported, as they tend to greatly reduce the size of the definition JSON

• schemas
• responses
• requestBodies
• examples

Due to their nature of being used very frequently, these should also be included:

• parameters
• headers
• pathItems

The full list of objects that can be referenced can be found here https://spec.openapis.org/oas/v3.1.0#components-object

Do we want to allow refs from other or even external documents?

[cwittern]

Any progress on this issue?

[line-o]

@cwittern this is the number one item on our backlog (see https://github.com/orgs/eeditiones/projects/2). When time allows this is the first thing to work on.

[line-o]

There is however a possibility to preprocess an API definition with refs see https://faq.teipublisher.com/api/designingopenapi/

[line-o]

The steps in short are

• npm install -g swagger-cli
• swagger-cli bundle --dereference -o api-with-inlined-references.json api-with-references.json

[cwittern]

Thanks, yes, that's an easy way out.

[line-o]

There is a new module out that can not only validate your API definition but also resolve references. It's called oad