OpenAPI reference docs

docStatic uses docusaurus-plugin-openapi-docs to generate API reference documentation from an OpenAPI specification. The plugin reads a spec file and writes a set of MDX files into your docs/ tree that Docusaurus then builds as normal pages.

Configuration

API sources are configured in config/docusaurus/index.json under the openapi.apis array. Each entry specifies a name, the path to the spec file, the output directory, and optional grouping options:

{
  "openapi": {
    "apis": [
      {
        "name": "petstore",
        "specPath": "openapi/petstore.yaml",
        "outputDir": "docs/api/petstore",
        "groupPathsBy": "tag",
        "categoryLinkSource": "tag"
      }
    ]
  }
}

Run generation with:

npm run gen-api-docs

To remove generated files:

npm run clean-api-docs

Tag pages

When groupPathsBy and categoryLinkSource are both set to "tag", the plugin creates a category index page for each OpenAPI tag (e.g. store.tag.mdx). By default these files contain a verbose boilerplate block that imports DocCardList and useCurrentSidebarCategory—both redundant in docStatic because DocCardList is already globally registered as an MDX component, and the component resolves the current category's items automatically when called with no props.

docStatic configures the plugin with a custom tag template that produces the simplified form instead:

<DocCardList />

The template is at config/docusaurus/openapi-tag-template.md and is wired in via the tagTemplate option in docusaurus.config.ts.

Editing generated tag files

The plugin only creates a tag file if one does not already exist—it will never overwrite a file you have edited. This means you can freely customise the description text in a tag page and it will survive subsequent gen-api-docs runs. Only newly introduced tags will have a file written for them, and those will use the custom template.

Related topics

• Blog – Blogging with docStatic.
• Introduction – Wiki sidebar generation and category index document conventions.
• Static assets – Static assets are the non-code files that are directly copied to the build output. Learn about how they are handled and the best practices for using static assets.
• Configuration – Configuring your site's behaviour through docusaurus.config.ts and more.
• Docs introduction – An introduction to docStatic docs.
• Internationalization – Translating documents with docStatic.
• Styling and layout – A Docstatic site is a pre-rendered single-page React application. You can style it the way you style React apps.