Integrate API reference docs into your developer portal

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:

• Directly integrate OpenAPI files as described in this guide.
• Use .page.yaml files described in the advanced guide.
• Use the API catalog.

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

pagination: section

pagination: item

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';

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