Docusaurus OpenAPI (beta)

OpenAPI plugin for generating API reference docs in Docusaurus v2.

Quick Overview

npx create-docusaurus-openapi my-website
cd my-website
npm start

Coming from v0.1.0? See the migration guide.

(npx comes with npm 5.2+ and higher)

Then open http://localhost:3000/ to see your site.
When you’re ready to deploy to production, create a minified bundle with npm run build.

Creating a new Site

You’ll need to have Node 14.0.0 or later version on your local development machine (but it’s not required on the server). We recommend using the latest LTS version. You can use nvm (macOS/Linux) or nvm-windows to switch Node versions between different projects.

To create a new site, you may choose one of the following methods:

• npx

  npx create-docusaurus-openapi my-website

  (npx is a package runner tool that comes with npm 5.2+ and higher)

• npm

  npm init docusaurus-openapi my-website

  npm init <initializer> is available in npm 6+

• yarn

  yarn create docusaurus-openapi my-website

  yarn create <starter-kit-package> is available in Yarn 0.25+

It will create a directory called my-website inside the current folder.
Inside that directory, it will generate the initial project structure and install the transitive dependencies:

my-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
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── .gitignore
├── openapi.json
├── docusaurus.config.js
├── babel.config.js
├── package.json
├── sidebars.js
└── README.md

• /docusaurus.config.js - A config file containing the site configuration. This can be used to configure the OpenAPI preset
• /openapi.json - The default OpenAPI definition that will be served (path can be configured in docusaurus.config.js).

For more info see project structure rundown.

Once the installation is done, you can open your project folder:

cd my-website

Inside the newly created project, you can run some built-in commands:

npm start or yarn start

Runs the site in development mode.
Open http://localhost:3000 to view it in the browser.

The page will automatically reload if you make changes to the code.

npm run build or yarn build

Builds the site for production to the build folder.

Docusaurus is a modern static website generator that will build the website into a directory of static contents, which can be copied to any static file hosting service like GitHub pages, Vercel or Netlify.

Add to an existing Site

1. Install the dependency

   npm install docusaurus-preset-openapi

2. Edit your docusaurus.config.js file to use this preset

   presets: [
     [
       "docusaurus-preset-openapi",
       /** @type {import('docusaurus-preset-openapi').Options} */
       {
         api: {
           path: "<PATH_TO_YOUR_OPENAPI_DOCUMENT>",
           routeBasePath: "/api",
         },
         docs: {
           sidebarPath: require.resolve("./sidebars.js"),
           routeBasePath: "/",
         },
         theme: {
           customCss: require.resolve("./src/css/custom.css"),
         },
       },
     ],
   ];

Popular Alternatives

Docusaurus OpenAPI is great for:

• Static generation All OpenAPI operations will be rendered as static pages at build time, giving many performance benefits.
• Demo panel Allow users to try out your API with an interactive demo panel.
• Native Docusaurus feel Built from scratch to work with Docusaurus.

Here are a few common cases where you might want to try something else:

• If you need better support for more advanced OpenAPI features, check out Redocusaurus. Redocusaurus embeds the much more mature OpenAPI documentation generator, Redoc, into Docusaurus as a React component.

Contributing

We encourage you to contribute to Docusaurus OpenAPI! Please check out the Contributing to Docusaurus OpenAPI guide for guidelines about how to proceed.

License

Docusaurus OpenAPI is released under the MIT License.