Add AsyncAPI descriptions

Transform your AsyncAPI description YAML or JSON file into interactive documentation by adding it to your project. Add one or multiple Event-Driven API (EDA) descriptions to your project.

Add individual description files to your project alongside your other content, or use an API catalog to showcase your EDAs alongside REST APIs and GraphQL.

Each AsyncAPI description is served at its own URL with its own automatically generated reference sidebar, whether or not you use a sidebars.yaml file. Use a sidebars.yaml file only when you want to place the reference alongside your other content with control over its order and grouping.

Realm supports Apache Kafka protocol bindings and renders labels for RabbitMQ's Advanced Message Queuing Protocol (AMQP). When Realm detects an AsyncAPI file containing Kafka bindings, it generates project pages with components specific to that protocol.

If your description file contains bindings from other protocols, the pages in your project may display some information as JSON code snippets instead of tables or forms.

Make sure you have the following:

• AsyncAPI description files in YAML or JSON format (3.0.0 version of AsyncAPI is supported)

To add an AsyncAPI description to your project, place the file or files in your project at the root or in a folder. When you run your project, each description is served as reference documentation with its own automatically generated sidebar.

To place the reference inside a custom sidebar alongside your other content, with control over its order and grouping, add your AsyncAPI description to a sidebars.yaml file. You can also link to the reference from anywhere, such as the navbar, an in-page link, a card, or an API catalog.

A sidebars.yaml file includes only the items you add to it, so add any files you want displayed in that sidebar, including AsyncAPI descriptions. For more information on configuring a sidebars.yaml file for your project, see Sidebar configuration.

To add an AsyncAPI file to your project with a sidebars.yaml file, add the page and label keys with the corresponding values for the AsyncAPI description to your sidebars.yaml file:

- page: apis/sample-api.yaml
  label: Sample API

If you have multiple AsyncAPI descriptions, use a group key for each description so that the different endpoints are only revealed when selected.

To add multiple AsyncAPI descriptions using group keys, update your sidebars.yaml file:

- group: Sample product 1 API
  items:
    - page: apis/sample-api-1.yaml
      label: Sample product 1 API
- group: Sample product 2 API
  items:
    - page: apis/sample-product-2.yaml
      label: Sample product 2 API

Realm supports AsyncAPI documents without further configuration. If you are using the deprecated AsyncAPI plugin, Redocly recommends migrating to the built-in docs tool.

To migrate to built-in AsyncAPI docs:

1. In the redocly.yaml file at the root of your project, delete the following lines:

   redocly.yaml

   plugins:
     - '@redocly/portal-plugin-async-api/plugin.js'

2. Remove the @redocly/portal-plugin-async-api dependency from your package.json file:

   package.json

   {
     "name": "demo project",
     "version": "1.0.0",
     "description": "demo",
     "dependencies": {
       "@redocly/portal-plugin-async-api": "*"
     }
   }

Your AsyncAPI documentation is rendered using the built-in tool.

• API catalog configuration - Organize multiple API descriptions including AsyncAPI specifications with catalogs for better user experience and navigation
• Sidebar navigation setup - Configure navigation structures to help users discover and access your AsyncAPI documentation content
• AsyncAPI extensions - Use custom extensions in your AsyncAPI descriptions to create richer, more detailed documentation with enhanced features
• Navbar configuration - Add top-level links to your API references and other pages