Introduction

Docusaurus supports plugin that will help you visualize your OpenAPI in a Stripe like interface. I will be using a plugin from PaloAltoNetworks called docusaurus-openapi-docs for the implementation.

Before you Begin, you must have:

• a valid API description file.

• an IDE, I will be using VSCode.

• React 18 or lower. (The most common issue which frustrated me and I was going mental)

• Node.js and npm installed

Setting up your Docusaurus Project

You should execute the following npmcommand from the terminal. (The official documentation on Githubuses yarnbut I am using npm command for this purpose).

npm create-docusaurus@3.7.0 mysite --package-manager npm

The npm command installs the required dependencies and creates a docusaurus folder. When prompted, select classic(recommended).

PS C:\Users\Steve Jose\Documents\Docusaurus> npx create-docusaurus@3.7.0 website --package-manager npm    
? Select a template below... » - Use arrow-keys. Return to submit.
>   classic (recommended)
    Git repository
    Local template

Select Typescript from the language.

√ Select a template below... » classic (recommended)
? Which language do you want to use? » - Use arrow-keys. Return to submit.
    JavaScript
>   TypeScript

A directory with all the docusaurus file will be created.

website/
├── blog/                     # Contains Markdown files for blog posts
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs/                     # Documentation Markdown files
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src/                      # Source files for custom components and pages
│   ├── components/           # Custom React components
│   │   └── MyComponent.tsx
│   ├── css/                  # Custom CSS styles
│   │   └── custom.css
│   └── pages/                # Static pages (e.g., About, Home)
│       ├── styles.module.css
│       └── index.tsx         # Example TypeScript page file
├── static/                   # Static assets (images, downloads, etc.)
│   └── img/
├── docusaurus.config.ts      # Main configuration file for the site (in TypeScript)
├── package.json              # Project dependencies and scripts
├── README.md                 # Project documentation/readme file
├── sidebars.ts               # Sidebar configuration for the docs section (in TypeScript)
└── tsconfig.json             # TypeScript configuration file

Installing the OpenAPI Plugin

Run the following command from the terminal. This will take you into the directory where you installed Docusaurus. (Going forward, all the commands should be run from here.)

cd .\website\

Run the following command to install the dependencies for the plugin.

npm add docusaurus-plugin-openapi-docs
npm install docusaurus-theme-openapi-docs

Verify plugin installation(Important)

Run the following command to verify the plugin installation.

npm list docusaurus-plugin-openapi

The result should be the following.

website@0.0.0 C:\Users\Steve Jose\Documents\Docusaurus\website
└── docusaurus-plugin-openapi@0.7.6

website@0.0.0 C:\Users\Steve Jose\Documents\Docusaurus\website
└── docusaurus-theme-openapi-docs@4.3.7

If the terminal returns empty, run the following command to install react18 and rerun the previous commands.

npm install react@18 react-dom@18

Go to your docusaurus.config.ts to edit and add the following configuration.

 import { themes as prismThemes } from 'prism-react-renderer';
import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
import type * as Plugin from "@docusaurus/types/src/plugin";
import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs"; //add this if doesn't exist

// rest of your code

presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
          docItemComponent: "@theme/ApiItem",  //add this if doesn't exist
          editUrl:
            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
       // rest of your code
  plugins: [  // add this
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'api',
        docsPluginId: 'classic',
        config: {
          openapi: {
            specPath: "examples/openapi.yaml", // Path to your OpenAPI spec
            outputDir: "docs/api", // Directory to output the generated docs
            sidebarOptions: {
              groupPathsBy: 'tag',
            },
        } satisfies OpenApiPlugin.Options,
      }
    }
    ], themes: ['docusaurus-theme-openapi-docs']
  ],

// rest of your code.

Add the API description file to /examples directory.

website/
├── blog/                     
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs/                    
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── examples/
|   ├── openapi.yaml         // your yaml file.
├── src/                      
│   ├── components/         
│   │   └── MyComponent.tsx
│   ├── css/                
│   │   └── custom.css
│   └── pages/              
│       ├── styles.module.css
│       └── index.tsx        
├── static/                 
│   └── img/
├── docusaurus.config.ts    
├── package.json             
├── README.md               
├── sidebars.ts              
└── tsconfig.json

Verify the configuration

Run the following command to check if the configuration is correct.

npm run start

Generating OpenAPI Docs

To automatically generate all the .mdx files from your OpenAPI.yaml file, run the following command.

 npm run docusaurus gen-api-docs all

(The command will convert all the openapi.yaml files and create a .mdx files) Since, I only have one .yaml file, this distinction is irrelevant. (If you only want to run it for single API instead of all, specify the id from plugins of the configurations.

The command will generate docs/folder with all the .mdx files.

To view the API on your browser, run the following command

npm run start

View my live project.