claude-howto 实战用 doc-generator 技能从源码自动生成高质量 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 Code 实现 API 文档自动化的开发者讲解开源仓库 claude-howto 中内置的doc-generator技能Agent Skill它以可复用的 Skill 形式封装从源代码生成 API 文档的完整方法论规定统一的文档结构与按端点组织的编写规范。读完本文你将掌握该技能的元数据设计、文档结构模板、多语言示例cURL / JavaScript / Python的写法并结合仓库附带的generate-docs.py源码理解自动化提取端点信息的底层原理最终能把这套规范复制到自己的项目中直接使用。技能定位description 就是触发入口doc-generator技能的本体是 ja/03-skills/doc-generator/SKILL.md仓库根目录下对应英文原文 03-skills/doc-generator/SKILL.md其英文版 frontmatter 如下--- name: doc-generator description: Generate comprehensive, accurate API documentation from source code. Use when creating or updating API documentation, generating OpenAPI specs, or when users mention API docs, endpoints, or documentation. ---依据 03-skills/README.md 中关于 Agent Skills 渐进式加载Progressive Disclosure机制的描述name与description属于 Level 1 元数据每次会话启动时都会被加载每个 Skill 约占 100 tokens。description 中Generate ... from source codeUse when creating or updating API documentation ... mention API docs, endpoints, or documentation等措辞正是 Claude 判断何时自动激活该 Skill 的匹配关键词——当用户提到 API 文档、端点、OpenAPI 规范等主题时Skill 会被自动触发无需手动/doc-generator调用。因此在编写自定义 Skill 时应当像本技能一样遵循 03-skills/README.md 的最佳实践描述既要说明做什么也要列举何时用并包含与真实用户提问相符的触发词。产出清单六类 API 文档工件依据 SKILL.md 中的 Generates / 生成するもの 小节该技能可产出的文档类型包括OpenAPI / Swagger 规范—— 面向机器消费的接口契约可接入代码生成与接口调试工具链API 端点文档—— 面向开发者阅读的端点说明逐个描述方法与路径SDK 使用示例—— 展示不同语言客户端如何调用集成指南—— 说明第三方系统如何接入该 API错误码参考—— 集中列出错误码及其含义、排查建议认证指南—— 说明认证方式如 Bearer Token与权限要求。这份清单界定了一份完整 API 文档的内容边界也是编排文档目录时最先确定的顶层结构。核心方法论每个端点一套统一文档结构SKILL.md 的主体Documentation Structure / 各エンドポイントごと给出了一份按端点组织的标准 Markdown 模板这是整个技能最有复用价值的部分。它以GET /api/v1/users/:id为例完整规范如下Description用一两句话说明该端点的行为例如按用户 ID 返回单个用户资料。描述应聚焦该端点职责避免复述显而易见的 HTTP 语义。Parameters参数表NameTypeRequiredDescriptionidstringYesUser ID参数表是结构化的核心Name必须与路径模板、query 参数或请求体字段完全一致Type标注数据类型Required明确是否必填Description给出语义解释。仓库 07-plugins/documentation/templates/api-endpoint.md 将这一模板进一步细化为三类参数分节Path / Query / Request Body并补充了分页参数的默认值写法如page默认 1、limit默认 20可作为更完整场景下的参考扩展。Response响应示例模板要求为每个可能的状态码分别给出真实 JSON 响应体200 Success{ id: usr_123, name: John Doe, email: johnexample.com, created_at: 2025-01-15T10:30:00Z }404 Not Found{ error: USER_NOT_FOUND, message: User does not exist }注意模板刻意区分了成功响应直接返回资源对象与错误响应含机器可读的error错误码与人类可读的message。这种做法与仓库生态中的错误码约定一致——例如 07-plugins/documentation/templates/api-endpoint.md 中定义了VALIDATION_ERROR、NOT_FOUND等统一错误码结构。为每个状态码各写一个真实示例比只贴一份成功响应更能避免调用方踩坑这也是后续错误码参考文档的重要素材。Examples多语言调用示例模板要求同一端点至少给出三种调用示例便于不同技术栈的读者直接复制cURLcurl -X GET https://api.example.com/api/v1/users/usr_123 \ -H Authorization: Bearer YOUR_TOKENJavaScriptconst user await fetch(/api/v1/users/usr_123, { headers: { Authorization: Bearer token } }).then(r r.json());Pythonresponse requests.get( https://api.example.com/api/v1/users/usr_123, headers{Authorization: Bearer token} ) user response.json()三份示例的语义必须保持一致同一 URL、同一请求头、同一资源 ID仅语言不同。当仓库需要多语言翻译时本项目在ja/、uk/、vi/、zh/下维护多语言副本示例部分尤其要保持同步更新避免各语言版本漂移。配套源码generate-docs.py 的自动化提取原理SKILL.md 定义了文档应该长什么样而仓库在 03-skills/doc-generator/generate-docs.py 中额外附带了如何从源码自动提取素材的可运行脚本两者配合构成完整的生成链路。该脚本是单文件 Python 实现不依赖第三方库整体思路如下AST 解析ast.parse()读取目标源码文件构建语法树端点识别APIDocExtractor继承ast.NodeVisitor遍历语法树在visit_FunctionDef中按命名约定识别端点——函数名以get_或post_开头即被认定为 API 端点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)这里每个被识别端点提取四项信息name函数名、docstring通过ast.get_docstring获取的说明文字、params位置参数名列表、returns返回值类型注解缺失时回退为Any见_extract_return_type使用ast.unparse还原注解表达式。Markdown 渲染generate_markdown_docs()将提取结果按固定的# / ##结构拼装为 Markdown每个端点为一个小节依次输出 docstring、参数列表、返回类型并以---分隔。命令行用法为将 Python 源文件路径作为第一个参数传入python 03-skills/doc-generator/generate-docs.py path/to/your_module.py从源码结构可以推断该脚本是一套约定式convention-based最小实现——通过get_/post_命名前缀和 docstring 提取信息适合作为自动化生成器的第一层骨架。SKILL.md 模板则代表了更完善的第二层把脚本产出的粗粒度信息端点名、参数、返回类型加工成含参数语义表、分状态码响应体、多语言示例的最终交付物。两者衔接的启示是docstring 中的描述质量直接决定生成文档的质量因此应鼓励开发者在源码中为每个端点方法写好规范 docstring形成源码即文档源头的正向循环。生态协同文档插件的完整工作流doc-generator技能并不孤立。仓库的 07-plugins/documentation/README.md 提供了一个更完整的 Documentation Plugin两者在结构规范上完全同源可作为该技能落地为工程化工作流的扩展路径。该插件的generate-api-docs命令见 07-plugins/documentation/commands/generate-api-docs.md描述了一条六步流水线扫描 API 端点Scan API endpoints提取函数签名与 JSDocExtract function signatures and JSDoc按模块 / 端点组织Organize by module/endpoint生成含示例的 MarkdownCreate markdown with examples包含请求 / 响应模式Include request/response schemas补充错误文档Add error documentation。这六步与本 SKILL.md 的模板结构一一对应参数表对应第 2、3 步的提取物Response 示例对应第 5 步错误码结构对应第 6 步。此外07-plugins/documentation/commands/validate-docs.md校验文档中的损坏链接、验证代码示例、对照真实代码与 07-plugins/documentation/commands/sync-docs.md检测代码变更、定位过期文档、验证示例可用性分别覆盖了文档的事后质检与持续同步插件中的api-documenter子代理见 07-plugins/documentation/agents/api-documenter.md则专职负责生成端点文档。在项目中落地 doc-generator 的要点将本技能复制到自己的 Claude Code 项目时可按以下步骤进行建立目录创建.claude/skills/doc-generator/SKILL.md个人级为~/.claude/skills/doc-generator/SKILL.md将模板内容放入SKILL.md正文技能目录结构规范可参考 03-skills/README.md 中my-skill/的示例SKILL.md必选templates/、scripts/、references/按需携带且SKILL.md建议控制在 500 行以内依赖脚本将 03-skills/doc-generator/generate-docs.py 放入scripts/子目录让 Claude 在生成文档时优先调用脚本做批量提取再按模板结构人工编排保持描述精确frontmatter 的description直接影响自动触发命中率务必保留API docs、endpoints、OpenAPI、documentation等触发词依据 03-skills/README.md 的 Level 1 元数据加载机制与描述预算说明description 还被限制在 1% 上下文窗口或 8000 字符的回退预算内统一错误码参照 Response 模板维护一份稳定的错误码表如USER_NOT_FOUND、VALIDATION_ERROR并让各端点的错误示例引用同一套码表这是后续生成错误码参考文档的基础多语言示例同步cURL / JavaScript / Python 示例承载相同的调用语义新增或修改端点时必须三份一起更新避免示例失配。从整体看doc-generator的价值不在于复杂算法而在于把API 文档的编写规范沉淀为 Agent 可自动执行的知识用description触发、按统一模板产出、靠多语言示例提升可用性、借源码脚本降低提取成本。这套技能规范 辅助脚本 插件工作流的组合正是 claude-howto 项目强调的示例驱动、即插即用风格的直接体现。【免费下载链接】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），仅供参考