specificationsoas

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.

Solution

  • 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.