mcpField
A
api-documenter

api-documenter

github.com/zhaono1开发85718 次安装9 周前更新
代码仓库

关于 api-documenter

面向需要编写 API 文档的开发者，提供基于 OpenAPI/Swagger 的参考文档指导，涵盖端点、架构、认证与错误，并说明规范生成和验证方式。

主要功能

  1. 01OpenAPI 端点文档指导
  2. 02架构与属性说明建议
  3. 03认证和错误文档指导
  4. 04规范生成与验证指导

适用场景

  1. 01编写 API 参考文档
  2. 02记录端点参数和响应
  3. 03说明架构与认证要求
  4. 04生成或检查 OpenAPI 规范

安装

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

$npx skills add https://github.com/zhaono1/agent-playbook --skill api-documenter

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
references/
openapi-template.yaml
references/examples/
openapi-example.yaml
README.md
scripts/
generate_openapi.py
validate_openapi.py

详细介绍

API 文档编写者

专门使用 OpenAPI/Swagger 规范编写完整的 API 文档。

此技能的触发条件

在以下情况下触发：

  • 请求编写 API 文档
  • 创建 OpenAPI/Swagger 规范
  • 需要 API 参考文档
  • 提及“API 文档”

OpenAPI 规范结构

openapi: 3.0.3
info:
  title: API Title
  version: 1.0.0
  description: API description
servers:
  - url: https://example.com/api/v1
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      tags:
        - users
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

端点文档

每个端点都要记录：

必填字段
  • summary：简要说明
  • operationId：唯一标识符
  • description：详细说明
  • tags：用于分组
  • responses：所有可能的响应
建议字段
  • parameters：包含详细信息的所有参数
  • requestBody：适用于 POST/PUT/PATCH
  • security：身份验证要求
  • deprecated：如适用
示例
/users/{id}:
  get:
    summary: Get a user by ID
    operationId: getUserById
    description: Retrieves a single user by their unique identifier
    tags:
      - users
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The user ID
    responses:
      '200':
        description: User found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      '404':
        description: User not found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'

架构文档

最佳实践
  1. 使用引用共享架构
  2. 为所有属性添加说明
  3. 为字符串指定格式（email、uuid、date-time）
  4. 为复杂架构添加示例
  5. 标记必填字段
示例
components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          description: Unique user identifier
          example: "550e8400-e29b-41d4-a716-446655440000"
        email:
          type: string
          format: email
          description: User's email address
          example: "[email protected]"
        createdAt:
          type: string
          format: date-time
          description: Account creation timestamp

身份验证文档

记录身份验证要求：

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use your JWT token from /auth/login

错误响应

标准错误格式：

components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Application-specific error code
        details:
          type: object
          description: Additional error details

常见 HTTP 状态码：

  • 200：成功
  • 201：已创建
  • 204：无内容
  • 400：错误请求
  • 401：未授权
  • 403：禁止访问
  • 404：未找到
  • 409：冲突
  • 422：无法处理的实体
  • 500：内部服务器错误

脚本

从代码生成 OpenAPI 规范：

python3 scripts/generate_openapi.py --name <resource-name> --output openapi.yaml

验证 OpenAPI 规范：

python3 scripts/validate_openapi.py --input openapi.yaml

参考资料

  • references/openapi-template.yaml - OpenAPI 模板
  • references/examples/ - API 文档示例
  • OpenAPI 规范

评论

支持 Markdown