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

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:

•

First commit - API docs update:

code

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:

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