Generating and Publishing API Documentation
Installing the OpenAPI plugin, configuring docusaurus.config.ts, adding the Postman-exported spec, generating MDX pages, and matching the API version to 4.0.0.
The documentation site renders interactive API reference pages alongside the
written guides. Those pages are generated from an OpenAPI specification
exported from Postman, not hand-written. This document records how the OpenAPI
tooling was installed, how docusaurus.config.ts was configured, where the spec
was added, how the .mdx pages were produced, and how the API reference version
was matched to the main product version, 4.0.0.
Engineering reference
This is an engineering reference for people who maintain the API reference. The generated files it describes must not be edited by hand.
1. Install the OpenAPI dependencies
Two packages do the work
- a plugin that turns a spec into MDX pages, and
- a theme that renders those pages with the "Try it" console. Install both of them.
cd corespan_docs
npm install docusaurus-plugin-openapi-docs@^5.0.1 docusaurus-theme-openapi-docs@^5.0.1| Package | Role |
|---|---|
docusaurus-plugin-openapi-docs | Reads an OpenAPI spec and generates the .mdx reference pages |
docusaurus-theme-openapi-docs | Renders the generated pages, including the request console and schema views |
2. Configure docusaurus.config.ts
Three changes wire the tooling into the site.
Register the plugin. Add docusaurus-plugin-openapi-docs to the plugins
array with one entry per API set under config. The Composer API is configured
like this:
[
'docusaurus-plugin-openapi-docs',
{
id: 'api',
docsPluginId: 'classic', // generate into the classic docs plugin
config: {
composer_versioned: {
specPath: 'docs/api_examples/composer_apis.yaml',
outputDir: 'docs/composer/api_versioned/4.0.0',
baseUrl: '/docs/reference/composer/api_versioned/composer-apis',
downloadUrl: '/docs/openapi-spec/composer_apis.yaml',
showSchemas: true,
hideSendButton: false,
sidebarOptions: {
groupPathsBy: 'tag',
categoryLinkSource: 'tag',
},
version: '4.0.0',
label: 'v4.0.0',
},
// apiTwo: { … } for the AI Studio (workbench) spec
},
},
],Key fields:
specPathpoints at the source spec (see the next section).outputDiris where the generated.mdxpages are written — note the4.0.0segment, which carries the version into the output path.groupPathsBy: 'tag'groups endpoints into sidebar categories by their OpenAPI tag, andcategoryLinkSource: 'tag'gives each category a landing page built from the tag description.downloadUrlis the "Download spec" link on the generated pages. It points at a protected endpoint (/docs/openapi-spec/composer_apis.yaml), not a static file, so the spec is served only to an authorized reader.
Register the theme. Add docusaurus-theme-openapi-docs to the themes
array.
Route doc pages through the API item component. In the docs preset, set
docItemComponent: '@theme/ApiItem' so the generated pages render with the
OpenAPI theme instead of the default doc layout.
3. Add the OpenAPI spec exported from Postman
The Composer API is maintained in the Postman app. To publish it:
-
In Postman, open the Composer API definition and export it as an OpenAPI 3.0 specification in YAML.
-
Save the exported file into the site at the path the plugin reads:
docs/api_examples/composer_apis.yamlSpecs for each API live together in
docs/api_examples/. The AI Studio spec, for example, isdocs/api_examples/workbench_apis.yaml. -
Set the spec's
info.versionto4.0.0so the version inside the document matches the version the site publishes it under.
Re-exporting from Postman and overwriting this file is how the reference is kept in sync with the API: the next generation step rebuilds the pages from it.
4. Generate the MDX reference pages
Run the generation command from corespan_docs/. The project wraps it in an
npm script that first runs a pre-processing step
(scripts/fix-composer-token-demos.js) and then calls the plugin:
npm run gen-api-docs -- all # regenerate every configured API set
# or target one set by its config key:
npm run gen-api-docs -- composer_versionedThis reads composer_apis.yaml and writes the full reference into
docs/composer/api_versioned/4.0.0/, including:
- one
*.api.mdxpage per endpoint, plus its companionParamsDetails.json,RequestSchema.json, andStatusCodes.jsondata files - a
*.tag.mdxlanding page per tag group - the
composer-apis.info.mdxintroduction page - a generated
sidebar.jsdescribing the endpoint tree
To regenerate cleanly, remove the output first:
npm run clean-api-docs -- allThe generated files are build artifacts. Edit the Postman spec and regenerate
rather than editing the .mdx pages, because the next generation overwrites
them. Hand-authored introduction pages (such as before-you-begin.mdx,
authentication.mdx, and make-your-first-api-call.mdx) live in the same
directory and are referenced explicitly from the sidebar so the generator leaves
them in place.
5. Wire the generated pages into the sidebar
The generated endpoint tree is imported into sidebars.ts and combined with the
hand-authored introduction pages under a dedicated composerSidebar1 sidebar:
import api_versionedSidebar from './docs/composer/api_versioned/4.0.0/sidebar';
// …
items: [
{ /* Introduction category: before-you-begin, authentication, … */ },
...api_versionedSidebar.slice(1), // generated tag sections
],slice(1) drops the generated introduction entry so the hand-authored
Introduction category is used instead, while every generated tag section is kept.
6. Match the API docs version to 4.0.0
The API reference is versioned independently of the written docs, and it is
deliberately aligned to the main product's development version, 4.0.0 — the
same version the docs/ folder is labeled with (4.0.0 (Development)). The
version is set consistently in four places so the dropdown, URLs, and pages all
agree:
-
The plugin config sets
version: '4.0.0'andlabel: 'v4.0.0', and theoutputDirends in4.0.0. -
The spec sets
info.version: 4.0.0. -
docs/composer/api_versioned/versions.jsonregisters the version for the version selector:[ { "version": "4.0.0", "label": "v4.0.0", "baseUrl": "/docs/reference/composer/api_versioned/4.0.0/composer-apis" } ] -
sidebars.tsbuilds the version controls from that file:import composerVersions from './docs/composer/api_versioned/versions.json'; import { versionSelector, versionCrumb } from 'docusaurus-plugin-openapi-docs/lib/sidebars/utils'; // … { type: 'html', value: versionSelector(composerVersions) }, // version dropdown { type: 'html', value: versionCrumb('v4.0.0') }, // version breadcrumb
To publish a new API version later, generate into a new outputDir (for example
.../api_versioned/4.1.0), add an entry to versions.json, and import that
version's generated sidebar.js — the same pattern this 4.0.0 setup follows.
Related
- Building and Deploying the Docs Site — prerequisites, the build, and how documentation versions are configured.
- Authentication on Docusaurus — how the spec download and generated pages are gated once deployed.
Building and Deploying the Docsaurus Site via Vercel
Prerequisites, local setup, pushing to Bitbucket, connecting Vercel, and serving the site at corespan.ai/docs.
Authentication on Docusaurus
How the Corespan documentation site gates access with Supabase, a client render guard, and server-side protected assets.