CODEWITHSUNDEEP
specificationsoas
user4122863
user4122863

Reputation:

OAS with Includes

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.

Upvotes: -1

Views: 152

Answers (2)

George Marques
George Marques

Reputation: 875

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.

Upvotes: 1

Michal Miky Jankovský
Michal Miky Jankovský

Reputation: 4263

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

Upvotes: 1

Related Questions