Generate AsyncAPI documentation

This page will guide you through the steps necessary to generate AsyncAPI documentation in your project.

Before you begin

Make sure you have the following before you begin:

a redocly.yaml file in the root of your project
the Redocly package for the product you use (such as @redocly/realm) as a dependency in package.json

Local dependencies required

Redocly projects can be previewed locally without installing the dependencies but to add the AsyncAPI plugin it is required to have both Realm and the AsyncAPI plugin installed as local dependencies.

If you see the error Theme "@redocly/portal-plugin-async-api" not found, then check that you have the @redocly/realm package listed in package.json.

Install plugin

Install AsyncAPI plugin with your package manager:

npm

npm install @redocly/portal-plugin-async-api

yarn

yarn add @redocly/portal-plugin-async-api

pnpm

pnpm add @redocly/portal-plugin-async-api

Enable plugin in redocly.yaml

Enable AsyncAPI plugin in your project. For a complete plugin settings reference see AsyncAPI plugin reference.

redocly.yaml

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

Add AsyncAPI definition file to your project

Place AsyncAPI definition file in the desired directory of your project. If you do not have one yet, you can use one of the example files from AsyncAPI github repository.

Start the project

Run the project with the following command:

npx @redocly/cli preview

You may also want to add the AsyncAPI file to your sidebar.

View the documentation

Now you can access your AsyncAPI documentation in the project. The page URL is determined by the path to the AsyncAPI definition relative to the root of your project. For example, if relative path to the file is api/docs/redocly-museum-asyncapi.yaml, the documentation will be available at http://127.0.0.1:4000/api/docs/redocly-museum-asyncapi