update-api-docs

更新 API 文档

本技能将指导你根据生产环境的 OpenAPI 规范更新 API 参考文档。

概览

API 文档由 OpenAPI 规范通过 docusaurus-plugin-openapi-docs 生成。工作流程包括：

1. 从生产环境下载最新的 openapi.json
2. 替换本地规范文件
3. 重新生成 API 文档页面

文件位置

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

步骤

1. 运行更新脚本

docs/scripts/update-api-docs.sh 中的封装脚本会下载 OpenAPI 规范、替换本地文件，并一步完成文档重新生成。

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

该脚本会将规范写入 docs/docs/reference/openapi.json，然后依次运行 npm run clean-api-docs -- agenta 和 npm run gen-api-docs -- agenta。参数 agenta 指的是 docusaurus.config.ts 中定义的 OpenAPI 配置 ID。

2. 安装依赖（如需要）

如果这是全新克隆的仓库，或尚未安装依赖：

cd docs
npm install

这会生成：

• 每个端点对应的 .api.mdx 文件
• API 类别对应的 .tag.mdx 文件
• 用于导航的 sidebar.ts

5. 验证更改

你也可以启动开发服务器进行预览：

cd docs
npm run start

然后访问 http://localhost:5000/docs/reference/api，确认 API 文档能正确渲染。

提交指南

提交这些更改时：

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

故障排除

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

清理和生成命令需要配置 ID。请使用：

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

出现“docusaurus: not found”错误

请先在 docs/ 目录中运行 npm install。

关于 onBrokenMarkdownLinks 的弃用警告

这是已知警告，可以安全忽略。该问题将在未来迁移到 Docusaurus v4 时处理。

相关配置

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