API reference 101

Use this topic when you want this portal to publish an API reference from an OpenAPI YAML or JSON file.

This template uses docusaurus-plugin-openapi-docs to generate MDX pages, and docusaurus-theme-openapi-docs to render them (schemas, parameters, and a try-it panel).

Generated API pages live in a separate docs instance (docs-api/, route /api) so they can use @theme/ApiItem without affecting tabs and other MDX in the main docs/ tree.

What this demo includes

Piece	Location
OpenAPI source	openapi/sample-api.yaml
Generated reference pages	docs-api/sample/
API docs plugin + OpenAPI generator	docusaurus.config.js
API sidebar	sidebarsApi.js
Regenerate script	npm run gen-api-docs

Browse the result under the navbar API reference item, or open Sample Notes API.

Generate the reference

1. Put your OpenAPI file under openapi/ (or keep the sample and edit it).
2. Confirm the plugin entry in docusaurus.config.js points at that file and at an output folder under docs-api/.
3. From the repository root, run:

npm run gen-api-docs

That runs docusaurus gen-api-docs all and writes MDX (plus a sidebar.ts) into the configured outputDir.

4. Restart the dev server if it is already running, then open API reference in the navbar.

To remove generated files for a clean regenerate:

npm run clean-api-docs
npm run gen-api-docs

Point the plugin at your own spec

In docusaurus.config.js, under the docusaurus-plugin-openapi-docs plugin, edit the sample (or add another) config object:

docusaurus.config.js

sample: {
  specPath: 'openapi/sample-api.yaml',
  outputDir: 'docs-api/sample',
  sidebarOptions: {
    groupPathsBy: 'tag',
  },
},

Field	What to set
Config key (sample)	Stable id used by gen-api-docs
specPath	Path to your OpenAPI file
outputDir	Folder under docs-api/ for generated MDX
sidebarOptions.groupPathsBy	'tag' groups operations by OpenAPI tags

The companion docs plugin is configured like this:

docusaurus.config.js

{
  id: 'api',
  path: 'docs-api',
  routeBasePath: 'api',
  sidebarPath: './sidebarsApi.js',
  docItemComponent: '@theme/ApiItem',
},

After you change outputDir or add a second API id, import that folder’s generated sidebar.ts in sidebarsApi.js.

Wire the sidebar

Generated navigation lives in docs-api/sample/sidebar.ts. sidebarsApi.js imports it for the API reference navbar item. The template guide sidebar links to the same intro page.

When you add another API:

1. Add a config entry and run npm run gen-api-docs.
2. Import the new sidebar.ts in sidebarsApi.js.
3. Add a category (or sidebar items) that includes those generated items.

Checklist

Goal	Where
Edit the demo contract	openapi/sample-api.yaml
Regenerate pages	npm run gen-api-docs
Plugin / output paths	docusaurus.config.js
API sidebar	sidebarsApi.js
Guide sidebar link	sidebars.js → Creating an API reference
Browse the result	Navbar → API reference

Related topics

• Customising the template
• Creating topics
• Docusaurus OpenAPI Docs