该技能用于生成专业的 API 文档，帮助开发者集成你的 API，内容涵盖端点规范、认证、请求/响应示例以及交互式文档。
适用场景
- 文档化 REST API
- 创建 OpenAPI/Swagger 规范
- GraphQL API 文档
- SDK 与客户端库文档
- API 认证指南
- 速率限制文档
- Webhook 文档
- API 版本控制指南
快速开始（最小可用示例）
openapi: 3.0.3
info:
title: E-Commerce API
description: |
Complete API for managing e-commerce operations including products,
orders, customers, and payments.
## Authentication
All endpoints require Bearer token authentication. Include your API key
in the Authorization header: `Authorization: Bearer YOUR_API_KEY`
## Rate Limiting
- 1000 requests per hour for authenticated users
- 100 requests per hour for unauthenticated requests
## Pagination
List endpoints return paginated results with `page` and `limit` parameters.
version: 2.0.0
contact:
name: API Support
email: api@example.com
url: https://example.com/support
license:
name: MIT
url: https://opensource.org/licenses/MIT
// ... (see reference guides for full implementation)
参考指南 详细实现位于 references/ 目录：
- OpenAPI Specification Example：openapi: 3.0.3
- List Products：List Products
最佳实践
应当做的
- 使用 OpenAPI 3.0+ 规范
- 为每个端点包含请求/响应示例
- 记录所有查询参数和请求头
- 提供认证示例
- 包含错误响应格式
- 记录速率限制与分页
- 使用一致的命名约定
- 包含多语言 SDK 示例
- 记录 Webhook 负载
- 提供交互式 API 浏览器（Swagger UI）
- 对 API 文档进行版本管理
- 为破坏性变更提供迁移指南
不应做的
- 跳过错误响应文档
- 忘记记录认证
- 使用不一致的术语
- 留下未记录的端点
- 忽略弃用通知
- 跳过版本信息