with one click
update-api-docs
// Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs
// Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | update-api-docs |
| description | Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs |
This skill guides you through updating the API reference documentation from the production OpenAPI specification.
The API documentation is generated from an OpenAPI spec using docusaurus-plugin-openapi-docs. The workflow involves:
openapi.json from production| Purpose | Path |
|---|---|
| OpenAPI spec (source) | docs/docs/reference/openapi.json |
| Generated API docs | docs/docs/reference/api/*.api.mdx |
| Generated sidebar | docs/docs/reference/api/sidebar.ts |
| Docusaurus config | docs/docusaurus.config.ts |
The wrapper script at docs/scripts/update-api-docs.sh downloads the OpenAPI
spec, replaces the local file, and regenerates the docs in one step.
cd docs
# Default — fetch from production (live cloud API)
pnpm update-api-docs
# Explicit live cloud API
pnpm update-api-docs:live
# From a locally running API (http://localhost/api/openapi.json)
pnpm update-api-docs:local
# From an explicit local file
pnpm update-api-docs:file /path/to/openapi.json
The script writes the spec to docs/docs/reference/openapi.json and then
runs npm run clean-api-docs -- agenta followed by
npm run gen-api-docs -- agenta. The agenta argument refers to the OpenAPI
config ID defined in docusaurus.config.ts.
If this is a fresh clone or dependencies haven't been installed:
cd docs
npm install
This generates:
.api.mdx files for each endpoint.tag.mdx files for API categoriessidebar.ts for navigationOptionally, start the dev server to preview:
cd docs
npm run start
Then visit http://localhost:5000/docs/reference/api to verify the API docs render correctly.
When committing these changes:
First commit - API docs update:
docs(api): update OpenAPI spec from production
Include all changed files:
docs/docs/reference/openapi.jsondocs/docs/reference/api/*.api.mdxdocs/docs/reference/api/*.tag.mdxdocs/docs/reference/api/sidebar.tsThe clean and generate commands require the config ID. Use:
npm run clean-api-docs -- agenta
npm run gen-api-docs -- agenta
Run npm install in the docs/ directory first.
This is a known warning and can be safely ignored. It will be addressed in a future Docusaurus v4 migration.
The OpenAPI plugin is configured in docs/docusaurus.config.ts:
[
"docusaurus-plugin-openapi-docs",
{
id: "openapi",
docsPluginId: "classic",
config: {
agenta: {
specPath: "docs/reference/openapi.json",
outputDir: "docs/reference/api",
downloadUrl: "https://raw.githubusercontent.com/Agenta-AI/agenta/refs/heads/main/docs/docs/reference/openapi.json",
sidebarOptions: {
groupPathsBy: "tag",
categoryLinkSource: "tag",
},
},
},
},
],