Last updated

Integrate API reference docs into your developer portal

Deprecated docs

The developer portal beta is approaching end of life.

Use Realm and Reunite instead. Read the migration guide.

Your developer portal can seamlessly integrate and display API reference documentation generated from API definitions.

You can configure this in any of the following ways:

Limitations

Direct OpenAPI integration doesn't support multi-version APIs, integrating APIs from the Redocly API registry, restricting permissions with RBAC, or excluding specific API reference documentation from portal search results.

If you need those features, you must use the API catalog or advanced configuration with .page.yaml files.

Step 1: Add OpenAPI files to the portal

Add one or more OpenAPI definition files to your portal project. You can keep them in the project root or create custom folders to organize them alongside your other documentation pages.

Your OpenAPI files must be in YAML or JSON format. Any file extension after the first . character in the file name is ignored when generating the URL for the page. This means that you can name your files api.oas3.yaml or payments-api.oas.yaml, or payments-api.yaml.

In the examples in this guide, we've added a file named acme.oas.yaml to the openapi folder in the root of the project.

The portal supports single-file (bundled) and multi-file API definitions.

Customize API reference settings

To customize the behavior and appearance of your integrated API reference documentation, create or modify the Redocly configuration file in the root of your portal project.

In the configuration file, add any of the supported Reference settings to the theme.openapi section.

Example redocly.yaml

lint:
  rules:
    example-rule-name: error
theme:
  openapi:
    pagination: section
    showConsole: true
    theme:
      menu:
        backgroundColor: '#fffff'

Note that these settings apply to all your API reference documentation integrated directly with OpenAPI files. To use different settings for each integrated API reference page, you must use the advanced configuration with .page.yaml files.

Step 2: Add OpenAPI files to the sidebar

To make sure your integrated Reference docs are accessible from the portal sidebar, link to your OpenAPI files in your sidebars.yaml file.

Add the Reference docs page to the sidebar as path to the OpenAPI file itself using the page key. This adds all operations from your API definition to the sidebar without any explicit grouping.

However, some operations may be automatically displayed in groups if your API definition uses tags. You may define a group in the sidebars.yaml file manually.

Example sidebars.yaml

- group: Product docs
  pages:
    - label: Overview
      page: developer-portal/overview.md
- group: Reference docs
  pages:
    - page: openapi/acme.oas.yaml

The following tables illustrate the behavior of integrated Reference docs depending on the pagination settings in the Redocly configuration file, tags from the API definition, and sidebar link types.

pagination: none

TagsSidebar file linkTag link formatOperation link format
YesOne top-level sidebar item as the main group. Every tag is a subgroup with operations under it. Tags have their own links but are not separated from operations. All operations are on a single continuous page./reference/#tag/tagName//reference/#operation/operationId
NoOne top-level sidebar item with all operations under it. All operations are on a single continuous page.None/reference/#operation/operationId

pagination: section

TagsSidebar file linkTag link formatOperation link format
YesOne top-level sidebar item as the main group. Every tag is a subgroup with operations under it. Tags have their own links but are not separated from operations./reference/tag/tagName//reference/tag/tagName/#tag/tagName/operation/operationId
NoNot supported - sidebar links don't work.NoneNot supported

pagination: item

TagsSidebar file linkTag link formatOperation link format
Tags with descriptionsOne top-level sidebar item as the main group. Every tag is a subgroup with operations under it. A tag and its description have their own link and page separate from operations./reference/tag/tagName//reference/operation/operationId/
Tags without descriptionsOne top-level sidebar item as the main group. Every tag is a subgroup with operations under it. Tags don't have their own links or pages, and just expand when clicked.None/reference/operation/operationId
No tagsOne top-level sidebar item with all operations under it. Every operation is on its own page.None/reference/operation/operationId

Step 3: Use API reference docs in MDX pages

To use your OpenAPI definition files in MDX pages, you must first declare them in the oasDefinitions section of the portal siteConfig.yaml file.

Declare the API definition in the following format:

definitionId: target

Where definitionId can be any custom name of your choice. You use this name to refer to your API definition in MDX components.

You must provide the target as a path to the OpenAPI definition root file in your portal project.

oasDefinitions:
  acme: ./openapi/acme.oas.yaml

When you have declared your API definitions, you can use their definitionId with React components to display API reference docs in MDX pages. Pointers allow you to target and display specific parts of the API documentation.

The following components work with API reference docs:

They are supported by default in the portal. You can also develop your own components.

To display API reference docs in an .md file:

  1. Import the React component, such as OpenApiResponse:
import { OpenApiResponse } from '@redocly/developer-portal/ui';
  1. Use it as follows:

With code samples panel

<OpenApiResponse definitionId="acme" pointer="#/components/responses/CoyoteResponse" />

Without code samples panel

<OpenApiResponse definitionId="acme" pointer="#/components/responses/CoyoteResponse" hideSamples={true} />