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:

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

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:

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:

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",
        },
      },
    },
  },
],