oasDefinitions

Usage

To integrate Reference docs into the developer portal, you must link to the API definition root documents from the oasDefinitions section. We call this step "declaring your API definitions".

Add the oasDefinitions section to the top level of the siteConfig.yaml file.

Options

Declare the API definitions in the following format:

definitionId: target

where definitionId can be any custom name of your choice.

You can provide the target in any of the following ways:

  1. As a path to the API definition file in the developer portal project (example: ./openapi/acme.yaml)
  2. As a link to the API definition in Redocly API Registry (registry: https://api.redoc.ly/registry/testing_acme/example-api/1.0/bundle/main/openapi.yaml)
  3. As a direct file link to an external URL hosting the API definition (external: https://example.com/acme.yaml)

Using $ref to declare API definitions

You can declare your API definitions in a separate file, then link to it in the oasDefinitions section using $ref. The definitions in the linked file must follow the same definitionId: target format.

For example, if linking to the acme.yaml file:

$ref: ./openapi/acme.yaml

the contents of the file can be:

example: ./openapi/test.yaml
registry: https://api.redoc.ly/registry/testing_acme/example-api/1.0/bundle/main/openapi.yaml
external: https://example.com/acme.yaml

Examples

In siteConfigIn referenced file
meta:
  title: Example Developer Portal
  description: Learn how to work with Example APIs
oasDefinitions:
  example: ./openapi/test.yaml
  external: https://example.com/acme.yaml
  registry: https://api.redoc.ly/registry/testing_acme/example-api/1.0/bundle/main/openapi.yaml
meta:
  title: Example Developer Portal
  description: Learn how to work with Example APIs
oasDefinitions:
  $ref: ./openapi/acme.yaml