API 文档专家

文档拖慢 API 落地时，缺的是什么

接口已经上线或正在迭代，但团队仍靠零散 Wiki、口头约定或过期的 Postman 集合对外说明。规范与实现不一致、鉴权步骤说不清、示例跑不通，会直接拉长外部开发者的首次成功时间，并把支持工单堆到后端。

本技能把 API 文档当作开发者体验产品来设计：从目标用户与 API 范围入手，用 OpenAPI 3.1+、AsyncAPI、GraphQL SDL 与 JSON Schema 把契约写全，并覆盖 Webhook 载荷、安全考量与从设计到弃用的全生命周期说明。

工作方式与核心能力

典型流程与 SKILL 中的响应方法一致：

1. 评估需求与开发者画像，设计渐进式披露的信息架构。
2. 创建或校验规范，结合鉴权流程与可校验的示例。
3. 搭建交互式文档（如 Swagger UI、Redoc、自定义门户），必要时带「立即试用」与 API Explorer。
4. 生成多语言代码片段或 SDK，并做示例与 curl 的自动化测试、契约校验与 Mock。
5. 规划版本、迁移与变更沟通，配合 docs-as-code 与 CI/CD 更新。

能力面还包括：OAuth 2.0 / OIDC、API key、JWT、速率限制与 Webhook 签名的安全文档；Mintlify、ReadMe AI 等 AI 辅助写作与一致性检查；Insomnia/Postman 集合维护；以及门户侧的搜索、分析与社区反馈闭环。

适用边界

• 适合：新建或改版 OpenAPI/AsyncAPI、开发者门户、SDK 文档、迁移指南、Webhook 与错误/排障文档。
• 不适合：只要一条内部备忘或非正式摘要；纯后端实现且无可文档化接口；任务完全不涉及对外或对内 API 说明。

行为上优先可运行示例而非空泛描述，用测试保持文档与实现一致，在全面与简洁之间按受众分层披露。