How to Render an OpenAPI YAML file on Docusaurus with a plugin

This guide explains how to render an OpenAPI YAML file on docusaurus with the docusaurus-openapi-docs plugin.

For this guide:

• the Windows OS was used.
• The docusaurus project is Javascript only
• The project deploys on Vercel.

Write the API specification inside a yaml file and save. I saved the yaml file as ai-invoice.yaml under the path docs/api-documentation/reference/ai-invoice.yaml. This path means the ai-invoice.yaml is under a folder named reference, which is in a folder named api-documentation. And api-documentation is in a folder named docs. The docs folder should have been created automatically when you installed docusaurus.

Step 1: Install the plugin and theme

## Using npm
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs

## or yarn
yarn add docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs

Step 2: Configure the plugin in docusaurus.config.js

In docusaurus.config, look for presets and update it to resemble this:

    module.exports = {
    // ... your existing config ...
    presets: [
        [
        'classic',
        {
            docs: {
            sidebarPath: require.resolve('./sidebars.js'),
            // use ApiItem to get the OpenAPI UI components
            docItemComponent: '@theme/ApiItem',
            },
            theme: { customCss: './src/css/custom.css' },  // This line may already be there. If it is, do not add it again.
        },
        ],
    ],

    plugins: [
        [
        'docusaurus-plugin-openapi-docs',
        {
            id: 'api',                 // unique id for this plugin instance
            docsPluginId: 'classic',   // use the preset classic docs instance
            config: {
            aiInvoice: {
                specPath: 'docs/api-documentation/reference/ai-invoice.yaml',  	// This is the path to the yaml file
                outputDir: 'docs/api-documentation/api-reference',  
                sidebarOptions: {
                groupPathsBy: 'tag',            // optional: group endpoints by tag
                },
            },
            },
        },
        ],
    ],
    themes: ['docusaurus-theme-openapi-docs'],
    };

Important things to note;

• specPath: is the path to the yaml file. Mine is 'docs/api-documentation/reference/ai-invoice.yaml'
• outputDir: is the path to the folder where you want the plugin to generate the MDX files. From the example, it is 'docs/api-documentation/api-reference’
  Adjust both based on your project.

Step 3: Tell your sidebars.js to show the generated docs

You should have a sidebar.js at the root of your repository.

    module.exports = {
    // your main docs sidebar (example)
    portfolioSidebar: [{ type: 'autogenerated', dirName: '.' }],

    // This is the new sidebar for API docs (which shows everything under docs/api-reference)
    apiAutomationSidebar: [
        { type: 'autogenerated', dirName: 'api-reference' },
    ],
    };

For me, I wanted to include the generated file under a sidebar navigation named API Documentation.

Step 4: Generate MDX from the YAML file

Generate the mdx file locally. At the end of the command, use the config key from step 3. From the example, it is sampleAi. To generate mdx files for all openAPI docs, replace the key (sampleAi) with all

# Using npx
npx docusaurus gen-api-docs sampleAi

# or with yarn
yarn docusaurus gen-api-docs all

Your terminal should look like this

You should now have at least 2 new mdx files generated in your OutputDir specified in Step 3.

Step 5: The generated sidebar

If the plugin creates a sidebar.ts in the outputDir, you can:

• Merge it with your sidebar.js (this tutorial doesn’t cover this)
• Delete it and rely on the autogenerated slice you added in sidebars.js.
• Ignore it. The generated MDX files are enough.

Step 6(Optional): Update scripts under package.json

This ensures Vercel runs npm run build, so the API docs are included in the deployed site. If you’re not using vercel, skip this step.

In your package.json in your root directory, check for the scripts object. Update it with the following command. NOTE: You may have scripts like start and build already. Simply add “npm run gen-api && ”

"scripts": {
"gen-api": "npx docusaurus gen-api-docs aiInvoice",
"start": "npm run gen-api && docusaurus start",
"build": "npm run gen-api && docusaurus build",
"serve": "docusaurus serve"
}

It should look like this:

Step 7: Preview your site locally

Run npm run start. You should see something like this:

---

🛠 Troubleshooting & common errors

Issue	Fix
Docs not showing after generation	Run npm run build locally and check if .mdx files exist under docs/api-reference
Autogenerated sidebar not working	Confirm sidebars.js includes { type: 'autogenerated', dirName: 'api-reference' }
Package.json file not found	Double-check your package.json for proper spellings, braces and commas where appropriate

🎯 Quick Checklist

1. Installed plugin and theme
2. Configured docusaurus.config.js
3. Updated sidebars.js
4. Generated .mdx files
5. Updated package.json
6. Successfully built and deployed

---

Removing the Generated Info File

The site deployed successfully. But it also displayed the info page which is based on the info object in the .yaml file.

The following steps explain how to prevent the info page from displaying.

1. In the OutputDir, you’ll notice that 2 mdx files are generated with the following extensions:
   • .info.mdx → The info page
   • .api.mdx → the actual API reference page which you need
2. Adjust sidebar.js by specifying the actual filepath. Instead of: { type: 'autogenerated', dirName: 'api-documentation/api-reference' }, use the file path: 'api-documentation/api-reference/generates-an-invoice-based-on-provided-instructions'.

Adjust to match your project structure. You can also rename the file title in the file frontmatter.
Add it under a category in the sidebar.

Or add it as a stand-alone page in the sidebar.