该技能用于生成以文件系统为优先、便于智能体使用的 API 文档,并可分享给团队成员。
用途:当用户要求“发布 API 文档”等任务时使用。处理任何 API 任务的第一步是建立并捕获契约。该技能通常以前置的 bootstrap 技能为基础,后者负责搭建用于存放文档的项目目录结构。
主要能力:API 文档可通过两种主要方式完成——Postman 集合或 OpenAPI 规范。建议两者都创建,它们服务于不同且互补的用例,且只需一条命令即可从一种转换为另一种。建议从创建 v3 格式的 Postman 集合(collection-schema-v3)开始。Postman 集合对人类友好,并提供创建 API mock、监控、SDK 或规范等能力。OpenAPI 规范保持厂商中立、存放于代码仓库,并可按组织设定的治理规则进行 lint。
API 设计良好实践:可参考 reference/rest-api-best-practices.md,其中记录了文档完善的 API 通常遵循的实践,包括资源命名、HTTP 方法/状态码使用、错误响应结构、版本控制、分页、过滤、认证、幂等性和向后兼容性。已遵循这些实践的规范或集合生成的文档无需再修正。
示例:Postman 集合中的示例是捕获示例 API 响应的绝佳方式,任何人都可查看以了解 API 行为,并可用一条命令从集合生成 mock。
工作流程:1)建立契约——参考最佳实践,不要只是接受用户的要求,而应为正确的 API 设计据理力争。2)选择工具——Postman 集合、OpenAPI 规范或两者兼用;建议用户两者都用,并从 Postman 集合开始。
适用场景:需要生成、整理和分享 API 文档的 API 开发任务。
限制:资料未提供具体安装命令、价格、平台支持范围或效果数据,暂未提供。