Claude Code 插件实战:用 /generate-api-docs 从源码自动生成完整 API 文档

原创2026-09-09 20:08:131,886 阅读
文章标签:文档教程开发工具

Claude Code 插件实战:用 /generate-api-docs 从源码自动生成完整 API 文档

/generate-api-docs 是 claude-howto 仓库 documentation 插件 中用于从源代码生成 API 文档的核心斜杠命令。本文以 zh/07-plugins/documentation/commands/generate-api-docs.md 为主线,结合插件内的子代理定义、文档模板以及仓库中可运行的 generate-docs.py 脚本,完整讲解「扫描端点 → 提取签名与 JSDoc → 组织内容 → 输出 Markdown」这条自动生成流水线,并给出可在真实项目中直接套用的模板与最佳实践。读完你将掌握:如何安装文档插件、如何驱动该命令完成一次端到端的 API 文档生成、文档输出应包含哪些字段,以及如何用配套的同步与校验命令保持文档长期不过期。

命令是什么:文档插件四大斜杠命令之一

在 claude-howto 的 07-plugins/documentation/ 目录中,documentation 插件把文档相关的自动化能力打包成一组可安装的组件,其中斜杠命令共有四个:

命令 作用 定义文件
/generate-api-docs 从源代码生成 API 文档 generate-api-docs.md
/generate-readme 创建或更新项目 README generate-readme.md
/sync-docs 让文档与代码变更保持同步 sync-docs.md
/validate-docs 校验文档的完整性与准确性 validate-docs.md

每条命令都是一个带 YAML frontmatter 的 Markdown 文件,frontmatter 中的 name 和 description 决定了命令的显示名称与触发说明。以 /generate-api-docs 为例,其定义开头为:

---
name: 生成 API 文档
description: 从源代码生成完整的 API 文档
---

安装整个文档插件只需一条命令(需 Claude Code 2.1+):

/plugin install documentation

安装完成后即可在会话中直接调用:

/generate-api-docs

六步生成流水线:命令的核心工作流程

/generate-api-docs 的价值在于它把「读源码、写文档」这件繁琐工作固化为一条可复现的六步流水线,命令定义 明确列出了全部六个阶段:

  1. 扫描 API 端点 —— 定位项目中所有对外暴露的接口入口;
  2. 提取函数签名和 JSDoc —— 从源码注释与类型标注中抽取结构化信息;
  3. 按模块 / 端点组织内容 —— 以业务模块为纲,把零散端点归类;
  4. 创建带示例的 Markdown —— 为每个端点补齐可复制的调用示例;
  5. 包含请求 / 响应 schema —— 给出请求体与各状态码响应的 JSON 结构;
  6. 添加错误文档 —— 汇总错误码、错误消息及其语义。

这六步并非孤立执行,而是在 documentation 插件 README 中描述的完整工作流中串起来的。README 给出了一个典型的执行现场:

User: /generate-api-docs

Claude:
1. Scans all API endpoints in /src/api/
2. Delegates to api-documenter subagent
3. Extracts function signatures and JSDoc
4. Organizes by module/endpoint
5. Uses api-endpoint.md template
6. Generates comprehensive markdown docs
7. Includes curl, JavaScript, and Python examples

Result:
✅ API documentation generated
📄 Files created:
   - docs/api/users.md
   - docs/api/auth.md
   - docs/api/products.md
📊 Coverage: 23/23 endpoints documented

从这个流程可以看到三个关键设计:

  • 范围可控:命令默认从 /src/api/ 这类约定的目录开始扫描,而不是漫无目的地遍历整个仓库;
  • 专业分工:Claude 不亲自逐行写文档,而是把任务委托给 api-documenter 子代理(该代理只被授予 Read, Write, Grep 三类工具,专注文档产出);
  • 模板驱动:输出严格套用 api-endpoint.md 模板,保证每个端点文档的结构一致。

最终产物按模块落盘,如 docs/api/users.md、docs/api/auth.md、docs/api/products.md,并附带覆盖率统计(如 23/23 端点已覆盖),方便你判断还有哪些接口没写进文档。

输出规范:端点文档模板字段全解

为了让生成的文档既完整又风格统一,插件内置了 api-endpoint.md 作为 REST 端点的标准模板。它规定了每个端点文档必须包含的字段,这也是 /generate-api-docs 提取源码信息后要填充的目标结构:

标题与描述

模板以 # [METHOD] /api/v1/[endpoint] 开头,紧接着是 ## Description,用一两句话说明该端点做什么、在什么场景下被调用。

认证说明

## Authentication 记录该端点要求的认证方式,例如 Bearer token、API Key 或 OAuth scope。没有认证的公开端点也应显式标注,避免调用方误判。

参数三分类

模板把参数拆成三类,分别用表格描述,每张表都包含 Name / Type / Required / Description 四列:

  • Path Parameters:路径中的资源标识符,如 id: string, Yes, Resource ID;
  • Query Parameters:查询串参数,如分页 page: integer, No, Page number (default: 1) 与 limit: integer, No, Items per page (default: 20)。模板示例中还给出了默认值,这是生成文档时应尽量补齐的信息;
  • Request Body:以 JSON 代码块给出请求体示例。
{
  "field": "value"
}

响应与错误文档

这是「包含请求 / 响应 schema」与「添加错误文档」两步的落点。模板对每个状态码给出独立小节和 JSON 示例:

  • 200 OK:成功响应结构,含 success 与 data 字段;
  • 400 Bad Request:参数校验失败,错误对象含 code: VALIDATION_ERROR 与 message: Invalid input;
  • 404 Not Found:资源不存在,错误对象含 code: NOT_FOUND 与 message: Resource not found。
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

这种「统一错误包裹结构」的意义在于:错误码字符串(如 VALIDATION_ERROR、NOT_FOUND)是可机器消费的,客户端可以据此做分支处理,而 message 只面向人类展示。生成文档时应从源码的异常处理分支中抽取这些错误码,而不是编造。

多语言调用示例

模板要求每个端点至少提供三种调用方式,分别对应开发者最常用的工具与语言:

cURL

curl -X GET "https://api.example.com/api/v1/endpoint" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('/api/v1/endpoint', {
  headers: {
    'Authorization': 'Bearer token',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

Python

import requests

response = requests.get(
    'https://api.example.com/api/v1/endpoint',
    headers={'Authorization': 'Bearer token'}
)
data = response.json()

附加信息

模板末尾还包含 Rate Limits(限流策略,如认证用户 1000 次/小时、公开端点 100 次/小时)与 Related Endpoints(相关端点导航),这两项在生成时通常需要结合部署配置或网关策略补充。

函数级文档:另一个输出维度

并非所有 API 都是 REST 端点。对于内部 SDK、工具函数或非 HTTP 接口,插件提供了 function-docs.md 模板,用于生成函数级文档,其结构与端点模板对应「提取函数签名和 JSDoc」这一步:

  • Signature:用 TypeScript 风格写出函数签名,如 function functionName(param1: Type1, param2: Type2): ReturnType;
  • Parameters:参数表格,标注类型、是否必填与含义;
  • Returns:返回类型与返回值语义;
  • Throws:可能抛出的异常,如 Error(非法输入)与 TypeError(类型错误);
  • Examples:Basic Usage 与 Advanced Usage 两档示例;
  • Notes:性能注意点与最佳实践;
  • See Also:相关函数或文档链接。
function functionName(param1: Type1, param2: Type2): ReturnType

这套函数文档字段恰好覆盖了 JSDoc / docstring 中常见的 @param、@returns、@throws 标注,因此子代理在提取阶段可以低成本地完成「标注 → 表格」的映射。

源码级原理:AST 解析器如何「提取函数签名」

「提取函数签名和 JSDoc」这一步听起来抽象,claude-howto 仓库其实给出了一个可直接运行的参考实现:03-skills/doc-generator/generate-docs.py(对应 doc-generator skill,其能力描述明确包含 API 端点文档、OpenAPI 规范、SDK 示例、错误码与认证指南的生成)。

该脚本用 Python 标准库 ast 模块实现了最小可用的 API 文档提取器,核心逻辑是 APIDocExtractor(继承 ast.NodeVisitor):

def visit_FunctionDef(self, node):
    """Extract function documentation."""
    if node.name.startswith("get_") or node.name.startswith("post_"):
        doc = ast.get_docstring(node)
        endpoint = {
            "name": node.name,
            "docstring": doc,
            "params": [arg.arg for arg in node.args.args],
            "returns": self._extract_return_type(node),
        }
        self.endpoints.append(endpoint)
    self.generic_visit(node)

可以从中提炼出「签名提取」的三条关键规则:

  • 端点识别靠命名约定:以 get_ / post_ 前缀命名的函数被当作 API 端点候选——这与 REST 的 HTTP 方法一一对应;
  • 描述来源是 docstring:ast.get_docstring(node) 直接从函数文档字符串抽取人类可读描述,即「JSDoc/docstring 提取」的最小实现;
  • 签名信息来自 AST 节点:参数列表取 node.args.args,返回类型取函数注解 node.returns,缺省时回退为 Any。

随后 generate_markdown_docs() 把提取结果拼装为 Markdown:

def generate_markdown_docs(endpoints: list[dict]) -> str:
    docs = "# API Documentation\n\n"
    for endpoint in endpoints:
        docs += f"## {endpoint['name']}\n\n"
        docs += f"{endpoint['docstring']}\n\n"
        docs += f"**Parameters**: {', '.join(endpoint['params'])}\n\n"
        docs += f"**Returns**: {endpoint['returns']}\n\n"
        docs += "---\n\n"
    return docs

使用方法(脚本接受一个源码文件路径作为参数):

python3 generate-docs.py path/to/api.py

这个脚本验证了一条重要事实:「提取函数签名和 JSDoc」完全可以用语言自身的 AST 解析器自动化,Claude 的 /generate-api-docs 命令在更复杂语言(如 TypeScript/JSDoc)上执行的也是同一思路——解析语法树 → 抽取标注 → 映射为文档字段,只是覆盖面更广(还包括 schema、错误码与多语言示例)。脚本的 visit_FunctionDef 只遍历了函数定义,说明「按模块/端点组织」是更高一层对收集结果的分组动作。

子代理与工具边界:api-documenter 的职责

生成高质量 API 文档时,主线程 Claude 会把具体写作委托给 api-documenter。该子代理的定义文件同样使用 frontmatter 声明能力边界:

---
name: api-documenter
description: API documentation specialist
tools: Read, Write, Grep
---

其产出清单与 /generate-api-docs 的六步一一对应:

  • Endpoint documentation(扫描端点 → 输出端点文档)
  • Parameter descriptions(参数描述,对应模板中的参数表格)
  • Response schemas(响应 schema,对应请求/响应 schema 步骤)
  • Code examples (curl, JS, Python)(多语言示例)
  • Error codes(错误码,对应错误文档步骤)

值得注意的设计约束是 tools 字段只开放了 Read, Write, Grep——这意味着它被设计为纯文档工作者:只读源码、搜索模式、写 Markdown,不执行任意命令,不访问外部系统。这种最小权限分工既降低了误操作风险,也让文档任务可以并行委托给多个子代理。

文档的持续维护:同步与校验闭环

API 文档最大的敌人是过期。/generate-api-docs 只是起点,documentation 插件用另外两条命令构成维护闭环:

  • sync-docs.md:代码变更后同步文档,流程为「检测代码变更 → 找出过期文档 → 更新受影响文档 → 验证示例仍可运行 → 更新版本号」。这保证了函数签名、参数或错误码变动时文档能跟着改;
  • validate-docs.md:质量门禁,流程为「检查失效链接 → 验证代码示例 → 确保完整性 → 检查格式 → 对照真实代码校验」。其中「对照真实代码校验」与「验证示例仍可运行」两项直接呼应了生成阶段对 schema 与错误码的要求。

推荐的使用节奏是:

  1. 功能开发完成后运行 /generate-api-docs 生成或更新端点文档;
  2. 提交前运行 /validate-docs 做质量门禁,拦截断链与失真示例;
  3. 代码持续演进时用 /sync-docs 批量修复过期内容。

配合 README 生成命令 /generate-readme(生成项目概览、安装说明、用法示例、API 文档链接、贡献指南与 License 信息),可以在一套插件内完成「API 文档 → README → 校验」的全链路文档治理。

GitHub MCP 与可选的文档同步能力

documentation 插件还附带一个 MCP 服务器配置 github-docs-config.json,用于把文档同步流程接入 GitHub:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

使用时需要先设置 GitHub Token:

export GITHUB_TOKEN="your_github_token"

从配置可以看出:它通过 npx 启动官方的 GitHub MCP 服务器,Token 以环境变量注入而非硬编码在配置里,${GITHUB_TOKEN} 的占位写法保证了凭据不进版本库。启用后,Claude 可以在生成文档后直接创建 PR、同步文档变更或核对远端 API 定义。该 MCP 是可选依赖——纯本地生成 API 文档并不需要它,README 中也将 GitHub access 标注为 optional。

最佳实践清单

综合 documentation 插件 README 的最佳实践章节与上述实现细节,落地 /generate-api-docs 时建议遵循:

  • 让文档靠近代码:把生成结果放在 docs/api/ 下并与源码模块一一对应,降低查找成本;
  • 文档随代码变更而更新:把 /sync-docs 纳入日常开发流程,而不是发布前才补文档;
  • 示例必须可运行:curl / JavaScript / Python 示例都要保证真实可执行,validate 阶段会校验这一点;
  • 定期校验:用 /validate-docs 做断链、格式与真实代码一致性检查;
  • 用模板保证一致性:端点文档统一套用 api-endpoint.md,函数文档统一套用 function-docs.md;
  • 善用子代理分工:复杂文档任务委托给 api-documenter,它的最小工具集天然限制了误操作范围。

相关资源

登录后查看全文
claude-howto