adding-api-docs

用途

当用户要求添加 API 文档、Swagger、OpenAPI 规范或生成端点文档时，可使用本技能。其目标是为 API 生成 OpenAPI/Swagger 文档，包括端点 schema、请求/响应类型以及交互式文档界面。

检测 API 框架：检查项目使用的是 Express、Fastify、Next.js API routes、Hono、Django REST Framework、FastAPI 等。
针对不同框架生成 OpenAPI 规范：
- Node.js/Express：安装 swagger-jsdoc 和 swagger-ui-express，并基于路由处理函数上的 JSDoc 注解生成 OpenAPI 规范。
- Next.js API routes：手动创建 openapi.json 文件，或使用 next-swagger-doc 从路由处理函数生成，并在 /api/docs 提供该规范。
- FastAPI（Python）：文档内置于 /docs（Swagger UI）和 /redoc；需确保使用 Pydantic 模型定义请求/响应类型，以便自动生成 schema。
添加交互式文档 UI：在 /docs 路由提供 Swagger UI，或使用 Scalar/Redoc 作为更现代的替代方案。
定义 schema：为请求体和响应创建 Zod schema（或 JSON Schema），并在 OpenAPI 规范中引用；对于 TypeScript 项目，可使用 zod-to-openapi 从现有 Zod 校验器生成 schema。
添加认证文档：在 OpenAPI 的 securitySchemes 部分记录认证方案（Bearer token、API key、OAuth2）。

技能按步骤执行：先检测 API 框架，再根据框架选择对应的安装与生成方式。例如 Node.js/Express 场景下安装依赖：

npm install swagger-jsdoc swagger-ui-express
npm install -D @types/swagger-jsdoc @types/swagger-ui-express

随后在路由处理函数上添加 JSDoc 注解，例如：

/**
 * @openapi
 * /api/users:
 *   get:
 *     summary: List all users
 *     responses:
 *       200:
 *         description: A list of users
 */

如需交互式文档 UI，可安装 Scalar：

npm install @scalar/express-api-reference