Skip to content

πŸ¦• OpenAPI plugin for generating API reference docs in Docusaurus v2.

License

Notifications You must be signed in to change notification settings

longportapp/docusaurus-openapi

Β 
Β 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Docusaurus OpenAPI (beta)

OpenAPI plugin for generating API reference docs in Docusaurus v2.

license npm latest package npm downloads build
prettier Cypress.io jest PRs Welcome

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.

About

πŸ¦• OpenAPI plugin for generating API reference docs in Docusaurus v2.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 86.6%
  • CSS 7.2%
  • JavaScript 5.0%
  • MDX 1.2%