update-api-docs — Автоматическое обновление документации API по OpenAPI

--- name: update-api-docs description: Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus 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: 1. Downloading the latest `openapi.json` from production 2. Replacing the local spec file 3. 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 ```bash 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: ```bash cd docs npm install ``` ### 3. Clean existing generated API docs ```bash 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 ```bash 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: ```bash 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: 1. **First commit** - API docs update: ``` docs(api): update OpenAPI spec from production ``` 2. 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: ```bash 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`: ```typescript [ "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", }, }, }, }, ], ```