mcpField
A
adding-api-docs

adding-api-docs

github.com/spencerpauly开发868419 次安装13 周前更新
代码仓库

关于 adding-api-docs

用于为多种框架的 API 添加 OpenAPI 文档的技能，涵盖框架识别、规范与模式创建、交互式文档和身份验证说明。

主要功能

  1. 01识别 API 框架
  2. 02指导配置 OpenAPI 规范
  3. 03提供模式定义与生成方案
  4. 04指导设置交互式文档界面
  5. 05说明身份验证方案文档

适用场景

  1. 01为 API 添加 Swagger 或 OpenAPI 文档
  2. 02发布交互式端点文档
  3. 03记录 API 请求、响应和身份验证模式

安装

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

$npx skills add https://github.com/spencerpauly/awesome-cursor-skills --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