update-api-docs

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 1. 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. 2. Install dependencies (if needed) If this is a fresh clone or dependencies haven't been installed: cd docs npm install 3. 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 . 4. 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 5. 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" , } , } , } , } , ] ,