Last updated 7 months ago

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

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

    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} />