用途
该技能（api-documentation）用于为开发者创建较为完整的 API 文档，适合在以下场景使用：
- API 开发：新增端点时。
- 外部发布：公开 API 上线时。
- 团队协作：前后端接口定义时。
资料将其定位为处理 REST API、GraphQL schema 或 SDK 方法文档的技能，并覆盖 OpenAPI/Swagger 与交互式文档。
主要能力
根据资料，技能内容围绕以下环节展开：
- 编写 OpenAPI（Swagger）规范：给出 openapi 3.0.0 示例，包含 info、servers、paths、components（schemas、responses、securitySchemes）以及 security 配置，示例以用户管理 API 为例，涵盖 GET /users 与 POST /users、参数、响应、分页与错误响应引用。
- 从代码生成文档（JSDoc/装饰器）：提供 Express + TypeScript 的示例，通过 @swagger 注释描述接口并配合路由处理器实现。
- 交互式文档：给出 Swagger UI 的搭建示例，使用 swagger-ui-express 与 yamljs 加载 openapi.yaml，并配置 customCss 与 customSiteTitle。
- 示例与指南：给出 API 文档内容示例，包括认证（JWT）、获取令牌、使用令牌、创建用户、速率限制、分页、错误码等说明与 curl/json 示例。
使用方式
资料以分步骤指令形式组织：
- Step 1：OpenAPI（Swagger）Spec。
- Step 2：Generate Documentation from Code（JSDoc/Decorators）。
- Step 3：Interactive Documentation。
- Step 4：Examples & Guides。
其中 Step 2 的示例代码为 Express + TypeScript 下带 @swagger 注释的 router.post('/users') 实现；Step 3 的示例通过 app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(...)) 挂载文档页面。
此外，资料建议的文档输出结构为：
docs/ ├── README.md ├── getting-started.md ├── authentication.md ├── api-reference/ │ ├── users.md │ ├── auth.md │ └── products.md ├── guides/ │ ├── pagination.md │ ├── error-handling.md │ └── rate-limiting.md ├── examples/ │ ├── curl.md │ ├── javascript.md │ └── python.md └── openapi.yaml
适用场景
- 内部或外部 REST API 的文档编写与维护。
- 依据 OpenAPI/Swagger 规范组织接口定义。
- 在代码注释中维护接口说明并生成文档。
- 搭建交互式 API 文档页面（Swagger UI）。
- 为前端与后端协作提供接口定义。
- 编写认证、分页、限流、错误码等使用指南与 curl/JavaScript/Python 示例。
约束与限制
资料列出了必须遵守与禁止事项：
必须（MUST）：
- 提供可运行的代码示例。
- 不仅记录成功情况，也要记录失败情况。
- API 变更时同步更新文档。
禁止（MUST NOT）：
- 在示例中使用真实的 API 密钥或密码。
- 使用模糊描述，例如“returns data”。
最佳实践：
- 提供交互式文档（Swagger UI）。
- 为主要语言提供 SDK 与示例。
- 记录 API 变更（Changelog）。
参考资料列出 OpenAPI Specification、Swagger UI、Redoc。
元数据信息：当前版本 1.0.0，最后更新 2025-01-01，兼容平台为 Claude、ChatGPT、Gemini，标签包括 #API-documentation、#OpenAPI、#Swagger、#REST、#developer-docs、#documentation。
关于具体收费、价格、部署平台、实际效果等事实，资料未提供，暂未提供。