mcpField
A
adding-api-docs

adding-api-docs

github.com/revitalb-port开发057 次安装10 周前更新
代码仓库

关于 adding-api-docs

用于为 Web API 添加 OpenAPI 文档的编码技能，指导 Agent 识别框架、生成规范与模式，并配置交互式文档和认证说明。

主要功能

  1. 01识别 API 框架
  2. 02创建 OpenAPI 规范
  3. 03添加交互式文档界面
  4. 04定义请求与响应模式
  5. 05记录认证方案

适用场景

  1. 01为 Express API 添加 Swagger 文档
  2. 02为 Next.js 路由添加 API 文档
  3. 03使用 FastAPI 内置文档
  4. 04使 API 规范与代码保持同步

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/revitalb-port/skills-registry-demo --skill adding-api-docs

安装后在 Claude Code 中输入/adding-api-docs确认已加载。

详细介绍

添加 API 文档（OpenAPI）

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

步骤

  1. 检测 API 框架 — 检查是否使用 Express、Fastify、Next.js API 路由、Hono、Django REST Framework、FastAPI 等。

  2. 对于 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 规范：

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

  3. 对于 Next.js API 路由 — 手动创建 openapi.json 文件，或使用 next-swagger-doc 从路由处理程序生成。通过 /api/docs 提供该规范。

  4. 对于 FastAPI（Python） — 文档内置于 /docs（Swagger UI）和 /redoc。确保使用 Pydantic 模型定义请求/响应类型，以便自动生成架构。

  5. 添加交互式文档界面 — 在 /docs 路由提供 Swagger UI，或使用 Scalar/Redoc 作为现代替代方案：

    npm install @scalar/express-api-reference

  6. 定义架构 — 为请求正文和响应创建 Zod 架构（或 JSON Schema），然后在 OpenAPI 规范中引用它们。对于 TypeScript 项目，使用 zod-to-openapi 从现有 Zod 验证器生成架构。

  7. 添加身份验证文档 — 在 OpenAPI 的 securitySchemes 部分记录身份验证方案（Bearer 令牌、API 密钥、OAuth2）。

备注

  • 让规范与实际 API 保持同步 — 尽可能从代码生成，而不是单独维护 YAML 文件。
  • 为架构添加示例值，以提升开发者体验。
  • 让 API 文档与代码一起进行版本管理。

评论

支持 Markdown