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. Run the update script

The wrapper script at docs/scripts/update-api-docs.sh downloads the OpenAPI spec, replaces the local file, and regenerates the docs in one step.

cd docs

# Default — fetch from production (live cloud API)
pnpm update-api-docs

# Explicit live cloud API
pnpm update-api-docs:live

# From a locally running API (http://localhost/api/openapi.json)
pnpm update-api-docs:local

# From an explicit local file
pnpm update-api-docs:file /path/to/openapi.json

The script writes the spec to docs/docs/reference/openapi.json and then runs npm run clean-api-docs -- agenta followed by npm run gen-api-docs -- agenta. The agenta argument refers to the OpenAPI config ID defined in docusaurus.config.ts.

2. Install dependencies (if needed)

If this is a fresh clone or dependencies haven't been installed:

cd docs
npm install

This generates:

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