用途
该技能用于创建全面的 API 参考文档，面向开发者集成场景。资料将其定位为使用 OpenAPI 规范创建专业 API 文档，包含端点、认证与交互式示例，并适用于 REST API 的文档编写。
主要能力
- 以 OpenAPI 3.0 规范组织 API 文档。资料给出的示例为 OpenAPI 3.0.3，包含 info、servers、security、paths、components 等部分。
- 描述接口基础信息：标题、版本、描述与联系邮箱。示例中标题为 E-Commerce API，版本 1.0.0。
- 定义多环境服务器地址：示例包含生产环境 https://api.example.com/v1 与预发布环境 https://staging-api.example.com/v1。
- 定义安全方案：示例使用 bearerAuth，类型为 http，scheme 为 bearer，bearerFormat 为 JWT。
- 描述端点：示例为 GET /products，包含 summary、tags、查询参数 limit（整数，默认 20）与 category（字符串），以及 200 响应引用 ProductList schema。
- 定义组件 schema：示例中 Product 对象为 object 类型，必填字段为 id、name、price，字段类型包含 uuid 格式的 id、最大长度 200 的 name、最小值 0 的 price 以及 description。
使用方式
资料中以 OpenAPI YAML 片段展示了文档结构写法，并给出文档清单与最佳实践，用于指导文档编写过程。
- 文档清单：所有端点附示例；解释认证方式；说明错误响应；记录速率限制；解释分页；适用时记录 Webhooks；提供多语言 SDK 示例。
- 最佳实践：使用 OpenAPI 3.0+ 规范；包含请求/响应示例；记录所有参数与请求头；提供认证示例；启用交互式 API 探索；维护版本文档；为破坏性变更提供迁移指南。
- 可用工具：Swagger Editor / Swagger UI、Redoc、Postman Documentation、Stoplight。
适用场景
适用于需要为开发者提供 API 集成文档的 REST API 项目，尤其是希望以 OpenAPI 3.0+ 规范统一描述端点、认证、参数、响应与数据模型，并借助 Swagger、Redoc、Postman 或 Stoplight 等工具呈现与探索文档的团队。
限制
资料未提供具体收费、价格、平台兼容性、运行环境要求或代码安装命令等详细信息，暂未提供。