OAS with Includes

Question

New to OAS. Can someone recommend how you would create an OAS Specification with reusable files (or snippets) that can be included in multiple specifications? Every example I can see references to components in the same specification, but I want it to be a separate file so it can be referenced by multiple specifications.

Answer 1

The reference can be any relative URI. Most examples you find show references to the same file using the fragment of the URI, that is everything after the # (hash), but you can also put stuff before it, including a path to a different file.

E.g.:

# Pet.yml
Pet:
  type: object
  properties:
    name:
      type: string
      example: "doge"

# API.yml
...
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "./Pet.yml#/Pet"

This way you can split your spec into multiple files (and folders) and reuse those in multiple API specs as well.

Note: this assumes version 3 of OAS, not sure if it works with previous versions.

Answer 2

use https://redocly.com/docs/cli | npm i @redocly/cli

it's powerful toolbox with much more than just extended $refs

they support relative paths in filesystem and even remote URL in references ($refs)

when your definition with non-standard references is done just bundle it out

PS check out all other very useful commands