Update API Documentation

Overview

docusaurus-plugin-openapi-docs

1. Downloading the latest

   openapi.json

   from production
2. Replacing the local spec file
3. Regenerating the API documentation pages

File Locations

docs/docs/reference/openapi.json

docs/docs/reference/api/*.api.mdx

docs/docs/reference/api/sidebar.ts

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

2. Install dependencies (if needed)

cd docs
npm install

3. Clean existing generated API docs

cd docs
npm run clean-api-docs -- agenta

agenta

docusaurus.config.ts

4. Regenerate API docs

cd docs
npm run gen-api-docs -- agenta

• Individual

  .api.mdx

  files for each endpoint

• .tag.mdx

  files for API categories

• sidebar.ts

  for navigation

5. Verify the changes

cd docs
npm run start

http://localhost:5000/docs/reference/api

Commit Guidelines

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

npm run clean-api-docs -- agenta
npm run gen-api-docs -- agenta

"docusaurus: not found" error

npm install

docs/

Deprecation warning about onBrokenMarkdownLinks

Related Configuration

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