Update API Documentation
This skill guides you through updating the API reference documentation from the production OpenAPI specification.
Overview
The API documentation is generated from an OpenAPI spec using docusaurus-plugin-openapi-docs . The workflow involves:
-
Downloading the latest openapi.json from production
-
Replacing the local spec file
-
Regenerating the API documentation pages
File Locations
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
Steps
- Download the OpenAPI spec from production
curl -s "https://cloud.agenta.ai/api/openapi.json" -o docs/docs/reference/openapi.json
Important: The file should be saved in minified format (single line, no pretty-printing) to match the existing format in the repository. The curl command above preserves the original format from the server.
- Install dependencies (if needed)
If this is a fresh clone or dependencies haven't been installed:
cd docs npm install
- Clean existing generated API docs
cd docs npm run clean-api-docs -- agenta
The agenta argument refers to the OpenAPI config ID defined in docusaurus.config.ts .
- Regenerate API docs
cd docs npm run gen-api-docs -- agenta
This will generate:
-
Individual .api.mdx files for each endpoint
-
.tag.mdx files for API categories
-
sidebar.ts for navigation
- Verify the changes
Optionally, 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.
Commit Guidelines
When committing these changes:
First commit - API docs update:
docs(api): update OpenAPI spec from production
Include all changed files:
-
docs/docs/reference/openapi.json
-
docs/docs/reference/api/*.api.mdx
-
docs/docs/reference/api/*.tag.mdx
-
docs/docs/reference/api/sidebar.ts
Troubleshooting
"missing required argument 'id'" error
The clean and generate commands require the config ID. Use:
npm run clean-api-docs -- agenta npm run gen-api-docs -- agenta
"docusaurus: not found" error
Run npm install in the docs/ directory first.
Deprecation warning about onBrokenMarkdownLinks
This is a known warning and can be safely ignored. It will be addressed in a future Docusaurus v4 migration.
Related Configuration
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", }, }, }, }, ],