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. 提取函数签名与 JSDocExtract function signatures and JSDoc扫描之后Claude 会为每个候选函数提取签名参数名、类型、返回类型以及 JSDoc/docstring注释。参考实现中_extract_return_type通过ast.unparse(node.returns)还原类型注解无注解时回退为Anydef _extract_return_type(self, node): if node.returns: return ast.unparse(node.returns) return Any配合 frontmatter 中 subagent 声明07-plugins/documentation/agents/api-documenter.mdClaude 在提取阶段具备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. 生成带示例的 MarkdownCreate markdown with examples组织完成后Claude 使用 api-endpoint 模板生成 Markdown。模板 07-plugins/documentation/templates/api-endpoint.md 为每个端点规定了完整的结构# [METHOD] /api/v1/[endpoint]标题Description / Authentication 章节ParametersPath / Query / Request Body 三张表格Responses200、400、404 等状态码及 JSON 示例ExamplescURL / JavaScript / Python 三种语言的调用示例Rate Limits 与 Related Endpoints模板中每种语言都有可直接运行的示例例如 cURL 与 Pythoncurl -X GET https://api.example.com/api/v1/endpoint \ -H Authorization: Bearer YOUR_TOKEN \ -H Content-Type: application/jsonimport 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. 包含请求 / 响应 SchemaInclude 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 文档完整性的关键一环。安装与使用方式根据插件 README07-plugins/documentation/README.md安装插件后即可获得全部命令/plugin install documentation随后在项目目录下直接触发/generate-api-docsREADME 还描述了命令的完整执行链路Example WorkflowClaude 先扫描/src/api/下的端点委派给api-documentersubagent提取签名与 JSDoc按模块/端点组织套用 api-endpoint 模板最终生成包含 curl、JavaScript、Python 三种示例的 Markdown 文档并输出覆盖率统计。命令对运行环境有明确要求Claude Code 2.1README 标注 Requirements如需 GitHub 集成则配置 tokenexport GITHUB_TOKENyour_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标题SignatureTypeScript 签名Parameters 表格Returns含类型与描述Throws异常类型清单ExamplesBasic / AdvancedNotes 与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考