Claude Code 插件实战:用 /generate-api-docs 从源码自动生成完整 API 文档
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 的价值在于它把「读源码、写文档」这件繁琐工作固化为一条可复现的六步流水线,命令定义 明确列出了全部六个阶段:
- 扫描 API 端点 —— 定位项目中所有对外暴露的接口入口;
- 提取函数签名和 JSDoc —— 从源码注释与类型标注中抽取结构化信息;
- 按模块 / 端点组织内容 —— 以业务模块为纲,把零散端点归类;
- 创建带示例的 Markdown —— 为每个端点补齐可复制的调用示例;
- 包含请求 / 响应 schema —— 给出请求体与各状态码响应的 JSON 结构;
- 添加错误文档 —— 汇总错误码、错误消息及其语义。
这六步并非孤立执行,而是在 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 与错误码的要求。
推荐的使用节奏是:
- 功能开发完成后运行
/generate-api-docs生成或更新端点文档; - 提交前运行
/validate-docs做质量门禁,拦截断链与失真示例; - 代码持续演进时用
/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,它的最小工具集天然限制了误操作范围。
相关资源
- 命令定义(中文) 与 命令定义(英文):六步流水线的权威来源
- documentation 插件 README:安装、工作流示例与最佳实践
- api-endpoint.md 模板 与 function-docs.md 模板:输出结构标准
- api-documenter 子代理:文档生成的专业执行者
- generate-docs.py 与 doc-generator skill:AST 提取签名的可运行参考实现
- 插件总览:理解插件如何捆绑命令、子代理与 MCP 的架构背景