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