Back to Details

update-api-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Update API Documentation

更新API文档

This skill guides you through updating the API reference documentation from the production OpenAPI specification.
本技能将引导你从生产环境的OpenAPI规范更新API参考文档。

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
API文档是通过
docusaurus-plugin-openapi-docs
从OpenAPI规范生成的。工作流程包括：
  1. 从生产环境下载最新的
    openapi.json
  2. 替换本地规范文件
  3. 重新生成API文档页面

File Locations

文件位置

PurposePath
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
用途路径
OpenAPI规范（源文件）
docs/docs/reference/openapi.json
生成的API文档
docs/docs/reference/api/*.api.mdx
生成的侧边栏
docs/docs/reference/api/sidebar.ts
Docusaurus配置文件
docs/docusaurus.config.ts

Steps

步骤

1. Download the OpenAPI spec from production

1. 从生产环境下载OpenAPI规范

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.
bash
curl -s "https://cloud.agenta.ai/api/openapi.json" -o docs/docs/reference/openapi.json
重要提示： 文件应以压缩格式（单行，无美化排版）保存，以匹配仓库中的现有格式。上述curl命令会保留服务器返回的原始格式。

2. Install dependencies (if needed)

2. 安装依赖（如有需要）

If this is a fresh clone or dependencies haven't been installed:
bash
cd docs
npm install
如果是全新克隆仓库或尚未安装依赖：
bash
cd docs
npm install

3. Clean existing generated API docs

3. 清理已生成的现有API文档

bash
cd docs
npm run clean-api-docs -- agenta
The 
agenta
argument refers to the OpenAPI config ID defined in 
docusaurus.config.ts
.
bash
cd docs
npm run clean-api-docs -- agenta
agenta
参数指的是
docusaurus.config.ts
中定义的OpenAPI配置ID。

4. Regenerate API docs

4. 重新生成API文档

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
bash
cd docs
npm run gen-api-docs -- agenta
此命令将生成：
  • 每个接口对应的独立
    .api.mdx
    文件
  • API分类对应的
    .tag.mdx
    文件
  • 用于导航的
    sidebar.ts
    文件

5. Verify the changes

5. 验证更改

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.
（可选）启动开发服务器进行预览：
bash
cd docs
npm run start
然后访问
http://localhost:5000/docs/reference/api
验证API文档是否正确渲染。

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
提交更改时：
  1. 首次提交 - API文档更新：
    docs(api): update OpenAPI spec from production
  2. 包含所有更改的文件：
    • 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

出现“missing required argument 'id'”错误

The clean and generate commands require the config ID. Use:
bash
npm run clean-api-docs -- agenta
npm run gen-api-docs -- agenta
清理和生成命令需要配置ID，请使用：
bash
npm run clean-api-docs -- agenta
npm run gen-api-docs -- agenta

"docusaurus: not found" error

出现“docusaurus: not found”错误

Run 
npm install
in the 
docs/
directory first.
先在
docs/
目录下运行
npm install
。

Deprecation warning about onBrokenMarkdownLinks

关于onBrokenMarkdownLinks的弃用警告

This is a known warning and can be safely ignored. It will be addressed in a future Docusaurus v4 migration.
这是已知警告，可以安全忽略。该问题将在未来的Docusaurus v4迁移中解决。

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",
        },
      },
    },
  },
],
OpenAPI插件在
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",
        },
      },
    },
  },
],