API 文档生成
从 OpenAPI spec 或路由 handler + zod schema 生成 API 文档。
文档与重构进阶
为什么
GitHub 2024 调查发现 81% 的开发者预期 AI 工具未来一年在代码文档中更深度集成，为所有工作流中最高。镜像实际 schema（请求/响应结构、状态码）的 API 文档防'文档说 200 但代码返 201' bug。
从真相源生成保持对齐。
何时使用
任何公共 API 用此。仅内部端点跳过。
如何做
1. 源：OpenAPI spec，或路由 handler + zod schema。
2. 提示："每端点：方法、路径、认证、body schema、每状态响应 schema、示例"。
3. 生成 markdown 或 OpenAPI HTML。
4. 加 CI 重新生成检查；漂移失败。
5. 每端点含试用示例。
示例
POST /api/books
认证：bearer
Body：{ title: string, author: string }（zod）
响应：
201：{ id: string, title: string, author: string }
400：{ error: string }
示例：curl -X POST .../api/books -H "Authorization: Bearer ..." -d '{"title":"Dune"}'
常见问题
- ⚠重构后 Error: Cannot find module 'xxx' → 重跑 `npm install` 和 `npx tsc --noEmit`；重构常丢或重命名 import。
- ⚠缺错误响应：列出 handler 可返的所有状态码。
- ⚠错误：文档漂移：示例无法运行 → 在 CI 执行示例（`npm run docs:check`）；被测示例不会漂移。
最佳实践
- ✓从 schema（zod/OpenAPI）生成，非散文。
- ✓每端点含真实 curl 示例。
- ✓用具体指标衡量结果（节省时间、缺陷率、测试覆盖率），使实践可被论证和改进。
常见问题解答
什么是API 文档生成？
从 OpenAPI spec 或路由 handler + zod schema 生成 API 文档。 它可帮助开发者快速理解 API 文档生成 的核心价值与适用场景。
如何开始使用API 文档生成？
开始使用 API 文档生成，建议先掌握以下要点：源：OpenAPI spec，或路由 handler + zod schema。
API 文档生成 的常见误区有哪些？
使用 API 文档生成 时常遇到的问题包括：重构后 Error: Cannot find module 'xxx' → 重跑 `npm install` 和 `npx tsc --noEmit`；重构常丢或重命名 import。；缺错误响应：列出 handler 可返的所有状态码。；错误：文档漂移：示例无法运行 → 在 CI 执行示例（`npm run docs:check`）；被测示例不会漂移。。
API 文档生成 的最佳实践是什么？
API 文档生成 的最佳实践包括：从 schema（zod/OpenAPI）生成，非散文。；每端点含真实 curl 示例。；用具体指标衡量结果（节省时间、缺陷率、测试覆盖率），使实践可被论证和改进。。
如何深入学习API 文档生成？
从官方文档入手，再在 GitHub 上搜索真实示例；先在小实验仓库验证模式，再应用到生产代码。