Integrating API Reference with the Portal

The Redocly Portal provides the possibility to integrate the API definition. To do this, complete the following steps:

Inside of siteConfig.yaml, add a declaration of all of your API definitions:

oasDefinitions:
  petstore: ./openapi/petstore.yaml

The definition may be in expanded format -- OpenAPI Generator, then pass a path to the folder:

oasDefinitions:
  petstore: ./openapi/petstore/

The definition may also be a remote URL:

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

Manually create a file reference.page.yaml (you may name it differently) with the following contents:

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

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`	`showInfo` – Shows the API definition's description as an overview page. `expand` – Determines if it will be expanded into multiple menu navigation items automatically.

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

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