SuperAPI AI 工具集

adding-api-docs

编程与开发

查看项目

更新于 10-15 21:05

技能介绍

用途:当用户要求添加 API 文档、Swagger、OpenAPI 规范或生成端点文档时使用此技能。

主要能力:先检测 API 框架(Express、Fastify、Next.js API routes、Hono、Django REST Framework、FastAPI 等),再据此生成 OpenAPI 规范与交互式文档界面。

使用方式:Node.js/Express 下安装 swagger-jsdoc 与 swagger-ui-express:npm install swagger-jsdoc swagger-ui-express,以及 npm install -D @types/swagger-jsdoc @types/swagger-ui-express;通过路由处理器上的 JSDoc 注解(@openapi)生成规范。Next.js API routes 可手动创建 openapi.json,或用 next-swagger-doc 从路由处理器生成,并在 /api/docs 提供规范。FastAPI 内置 /docs(Swagger UI)与 /redoc,需使用 Pydantic 模型以自动生成 schema。交互式界面可在 /docs 提供 Swagger UI,或用 Scalar/Redoc 替代:npm install @scalar/express-api-reference。用 Zod 或 JSON Schema 定义请求体与响应 schema,TypeScript 项目可用 zod-to-openapi 从现有 Zod 校验器生成;在 securitySchemes 中记录认证方案(Bearer token、API key、OAuth2)。

限制与注意:应尽量从代码生成规范以保持与实际 API 同步,而非维护独立 YAML;为 schema 添加示例值;文档随代码一起版本化。资料未提供具体框架之外的更多细节。