api-docs-generator

api-docs-generator 是一项专业的软件代理技能，旨在缩短不断演进的源代码与技术文档之间的差距。通过监控代码变更，此工具确保 API 规范保持精确且易于访问，无需手动介入。它专为管理复杂后端服务并需要跨格式（包括 OpenAPI 和 Markdown）保持一致文档的工程团队与开发人员而建。其主要目标是最大限度地减少手动更新的负担，降低代码实现与文档之间出现差异的可能性。

• 自动分析存储库代码变更，以检测对 API 端点与架构的影响。

• 直接从源代码注释生成并维护结构化的 OpenAPI 规范。

• 更新并同步项目级 Markdown 文档，以反映架构上的变更。

• 与 GitHub Pages 等文档托管平台集成，实现无缝部署。

• 在解析或部署失败期间提供全面的错误处理与平滑降级机制。

• 确保不同文档格式之间的长期一致性，防止信息过时。

• 适用于高频率更新的项目，其中保持文档同步是每周运营的一大挑战。

• 最适合由涉及公开 API 签名或接口变更的 git commit 或 pull request 触发。

• 输入为干净且带有注释的源代码；输出为人类可读的 Markdown 及机器可读的 JSON/YAML OpenAPI 文件。

• Token 预算管理是核心优先级，针对 Claude Code 生态系统中的每周循环运营进行了优化。

• 建议与静态分析工具及代码审查子代理结合使用，以实现完整的“文档即代码”(Documentation-as-Code) 工作流程。

• 若解析自定义语言或非标准 API 装饰器时，请注意此技能的复杂依赖需求。