企业官网建设流程全解析

Claude How To 实战：用 /generate-api-docs 命令从源码自动生成完整 API 文档

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

本文是 Claude How To 仓库中 documentation 插件（07-plugins/documentation）的 API 文档生成命令指南。它对应 slash command 定义文件 generate-api-docs.md，面向需要在项目中快速产出端点到函数级 API 文档的开发者。读完本文，你将掌握/generate-api-docs的六步工作流、它背后的 subagent 与模板机制，以及如何结合仓库内的参考实现将文档生成自动化到 CI 流程中。

命令定位：一个 slash command 定义的解剖

该命令的本质是一个 Claude Code 插件中的 slash command，其 frontmatter 如下：

--- name: Generate API Documentation description: ソースコードから包括的な API ドキュメントを生成する ---

其中name是命令的展示名，description是触发语义描述——它告诉 Claude 这个命令「从源码生成全面的 API 文档」。在 Claude Code 中，开发者通过/generate-api-docs即可调用，而插件的完整命令集见 07-plugins/documentation/README.md：

• /generate-api-docs— 生成 API 文档
• /generate-readme— 创建或更新 README
• /sync-docs— 同步文档与代码变更
• /validate-docs— 校验文档

从仓库结构看，documentation 插件还提供了配套的 subagent、模板与 MCP 配置，形成一套完整的文档工程体系。

六步工作流：从源码扫描到文档成稿

原命令文档定义了生成完整 API 文档的六个核心步骤，这是整个命令的骨架，也是本文展开的重点。

1. 扫描 API 端点（Scan API endpoints）

第一步是让 Claude 扫描项目中的 API 端点。根目录版命令文档（01-slash-commands/generate-api-docs.md）给出了更具体的指令：

Scanning all files in/src/api/

这意味着命令默认将/src/api/目录作为扫描范围，Claude 会遍历该目录下所有源文件，识别出对外暴露的接口。从该文档的输出格式约定看，扫描后的产物目标是生成/docs/api.md这份 Markdown 文件。

仓库中的 03-skills/doc-generator/generate-docs.py 是一个可运行的最小参考实现，展示了「扫描」在代码层面如何落地：它基于 Python 标准库ast（抽象语法树）解析源文件，用visit_FunctionDef钩子遍历所有函数定义，并只收集以get_或post_开头的函数作为候选端点：

class APIDocExtractor(ast.NodeVisitor): def visit_FunctionDef(self, node): 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)

这段代码验证了命令的核心逻辑：通过命名约定（HTTP 动词前缀）识别端点、从 docstring 提取说明、从函数签名提取参数与返回类型。

2. 提取函数签名与 JSDoc（Extract function signatures and JSDoc）

扫描之后，Claude 会为每个候选函数提取签名（参数名、类型、返回类型）以及 JSDoc/docstring注释。参考实现中_extract_return_type通过ast.unparse(node.returns)还原类型注解，无注解时回退为Any：

def _extract_return_type(self, node): if node.returns: return ast.unparse(node.returns) return "Any"

配合 frontmatter 中 subagent 声明（07-plugins/documentation/agents/api-documenter.md），Claude 在提取阶段具备Read、Write、Grep三种工具能力，能够跨文件检索并阅读理解 JSDoc。

3. 按模块 / 端点组织（Organize by module/endpoint）

提取到的信息不能平铺直叙，需要按模块与端点分层组织。README 中的示例工作流（07-plugins/documentation/README.md）展示了组织后的产物形态：

📄 Files created: - docs/api/users.md - docs/api/auth.md - docs/api/products.md 📊 Coverage: 23/23 endpoints documented

即按业务模块（users、auth、products）拆分文档文件，并统计端点覆盖率，确保没有遗漏。

4. 生成带示例的 Markdown（Create markdown with examples）

组织完成后，Claude 使用 api-endpoint 模板生成 Markdown。模板 07-plugins/documentation/templates/api-endpoint.md 为每个端点规定了完整的结构：

• # [METHOD] /api/v1/[endpoint]标题
• Description / Authentication 章节
• Parameters（Path / Query / Request Body 三张表格）
• Responses（200、400、404 等状态码及 JSON 示例）
• Examples（cURL / JavaScript / Python 三种语言的调用示例）
• Rate Limits 与 Related Endpoints

模板中每种语言都有可直接运行的示例，例如 cURL 与 Python：

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

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

根目录命令文档进一步约定输出格式「Include curl examples for all endpoints」——即所有端点都必须附带 curl 示例，保证文档可被快速复制验证。

5. 包含请求 / 响应 Schema（Include request/response schemas）

第五步要求把请求体与响应体以结构化 Schema 形式写进文档。模板中 Request Body 与各状态码 Response 都使用 JSON 块呈现：

{ "success": true, "data": { "id": "123", "name": "Example" } }

错误响应也遵循统一格式（success/error.code/error.message结构），这与 03-skills/doc-generator/SKILL.md 中「Generate OpenAPI/Swagger specifications」的目标一致，说明该命令与技能可以互相配合产出规范级 Schema。

6. 添加错误文档（Add error documentation）

最后一步是补全错误语义。api-endpoint 模板专门为 400 与 404 等异常路径准备了章节：

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid input" } }

doc-generator 技能文档同样要求每个端点包含 404 之类的错误示例（如USER_NOT_FOUND）。错误文档让调用方无需阅读源码即可了解失败模式，是 API 文档完整性的关键一环。

安装与使用方式

根据插件 README（07-plugins/documentation/README.md），安装插件后即可获得全部命令：

/plugin install documentation

随后在项目目录下直接触发：

/generate-api-docs

README 还描述了命令的完整执行链路（Example Workflow）：Claude 先扫描/src/api/下的端点，委派给api-documentersubagent，提取签名与 JSDoc，按模块/端点组织，套用 api-endpoint 模板，最终生成包含 curl、JavaScript、Python 三种示例的 Markdown 文档并输出覆盖率统计。

命令对运行环境有明确要求：Claude Code 2.1+（README 标注 Requirements），如需 GitHub 集成则配置 token：

export GITHUB_TOKEN="your_github_token"

底层机制：subagent 委派与模板约束

api-documenter subagent

命令并非由单个 prompt 独立完成，而是会委派给专用 subagent。07-plugins/documentation/agents/api-documenter.md 声明了其职责边界：

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

它能产出：端点文档、参数说明、响应 Schema、curl/JS/Python 示例与错误码。限定的三个工具（Read、Write、Grep）恰好覆盖「读取源码 → 检索上下文 → 写入文档」的完整闭环，避免 subagent 过度调用其他能力。

function-docs 模板

对于非 HTTP 端点而是纯函数/方法的场景，命令可切换到 07-plugins/documentation/templates/function-docs.md，其结构包括：

• # Function: functionName标题
• Signature（TypeScript 签名）
• Parameters 表格
• Returns（含类型与描述）
• Throws（异常类型清单）
• Examples（Basic / Advanced）
• Notes 与 See Also

参考实现的generate_markdown_docs函数与之一致地按「函数名 → docstring → 参数 → 返回值」的次序渲染 Markdown，可作为该模板的落地样例：

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"

与插件其他命令协同：形成文档生命周期

/generate-api-docs不是孤立命令，它与 documentation 插件的另外三个命令构成闭环：

• generate-readme.md：生成 README，其中「API documentation links」一项会引用本命令产出的 API 文档；
• sync-docs.md：检测代码变更、定位过期文档、更新受影响章节并验证示例仍可用——这是 API 文档长期不被腐化的保障；
• validate-docs.md：检查坏链、验证代码示例、核对格式与完整性，并「Validate against actual code」，即拿文档与真实代码对照。

README 的最佳实践清单也呼应了这一闭环：让文档贴近代码、随代码变更更新、包含实用示例、定期校验、用模板保证一致性。在 CI 中，开发者可以在每次合入后依次执行/generate-api-docs→/sync-docs→/validate-docs，把 API 文档的生成与维护变成可重复的流程。

小结

/generate-api-docs命令以六步工作流（扫描端点 → 提取签名与 JSDoc → 按模块组织 → 生成带示例的 Markdown → 包含请求/响应 Schema → 补充错误文档）为核心，配合api-documentersubagent、api-endpoint与function-docs模板，以及sync-docs、validate-docs的联动，覆盖了 API 文档从生成到维护的全生命周期。仓库中的 generate-docs.py 则为理解其扫描原理提供了可直接运行的最小实现。需要说明的是，命令的实际效果依赖 Claude Code 2.1+ 运行环境与模型能力，仓库文档中标注的兼容模型范围（如 Claude Opus 5、Claude Sonnet 5 等）可作为选型参考。

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto