Integrating API reference docs into your developer portal

Step 1. Declare your API definition(s).

Inside of siteConfig.yaml, declare of all of your API definitions. The definition may be in a multi-file format or already bundled. It may be in JSON or YAML format.

You'll use the key name for further reference within the developer portal.

oasDefinitions:
  petstore: ./openapi/petstore.yaml

The value may also be a remote URL:

oasDefinitions:
  petstore: https://example.com/petstore.yaml

Step 2. Add pages that reference those definitions.

Manually create a file reference.page.yaml (you may name it differently, but it must have the .page.yaml file extension) with the following example contents:

type: redoc
definitionId: petstore
tags: ['pet', 'user']
showInfo: true
expand: true
settings:
  jsonSampleExpandLevel: 'all'

Field	Description
`type`	In the current version, only the `redoc` type is supported.
`definitionId`	References the key(s) declared in the `siteConfig.yaml`. In this example, the `petstore` is declared as the key.
`tags`	(optional) `showInfo` – Shows the API definition's description as an overview page. `expand` – Determines if it will be expanded into multiple menu navigation items automatically.
`showInfo`	(optional) Will show the info section of the API if true.
`expand`	(optional) Will split the API into a page per operation if true.
`settings`	(optional) Add any of Redocly's settings to this object

Here is an example snippet within the sidebars.yaml:

    pages:
      - page: reference.page.yaml#operation/createUsersWithArrayInput
      - page: reference.page.yaml/*

The first page displays only a specific operation.

The second page shows all operations (* is a wildcard).

Step 4. Use components from within MDX pages.

Within a .mdx file, you would import the component, such as RedocResponse:

import { RedocResponse } from '@redocly/ui';

Then you can use it as follows:

With Samples Panel:

<RedocResponse definitionId="petstore" pointer="#/components/responses/PetResponse" />

Without Samples Panel:

<RedocResponse definitionId="petstore" pointer="#/components/responses/PetResponse" hideSamples={true} />

Integrating API reference docs into your developer portal

Step 1. Declare your API definition(s).

Step 2. Add pages that reference those definitions.

Step 3. Reference the pages from the sidebar (or other places).

Step 4. Use components from within MDX pages.