Back to Details

api-documenter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Documenter

API 文档生成工具

Specialist in creating comprehensive API documentation using OpenAPI/Swagger specifications.
专门使用OpenAPI/Swagger规范创建全面的API文档。

When This Skill Activates

本技能的激活场景

Activates when you:
  • Ask to document an API
  • Create OpenAPI/Swagger specs
  • Need API reference documentation
  • Mention "API docs"
当你进行以下操作时激活：
  • 要求编写API文档
  • 创建OpenAPI/Swagger规范
  • 需要API参考文档
  • 提及"API docs"

OpenAPI Specification Structure

OpenAPI规范结构

yaml
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
yaml
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

Endpoint Documentation

端点文档

For each endpoint, document:
针对每个端点，需编写以下内容：

Required Fields

必填字段

  • summary: Brief description
  • operationId: Unique identifier
  • description: Detailed explanation
  • tags: For grouping
  • responses: All possible responses
  • summary: 简要描述
  • operationId: 唯一标识符
  • description: 详细说明
  • tags: 用于分组
  • responses: 所有可能的响应

Recommended Fields

推荐字段

  • parameters: All parameters with details
  • requestBody: For POST/PUT/PATCH
  • security: Authentication requirements
  • deprecated: If applicable
  • parameters: 包含详细信息的所有参数
  • requestBody: 适用于POST/PUT/PATCH请求
  • security: 认证要求
  • deprecated: （如适用）标记是否已弃用

Example

示例

yaml
/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'
yaml
/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'

Schema Documentation

Schema文档

Best Practices

最佳实践

  1. Use references for shared schemas
  2. Add descriptions to all properties
  3. Specify format for strings (email, uuid, date-time)
  4. Add examples for complex schemas
  5. Mark required fields
  1. 使用引用共享Schema
  2. 添加描述到所有属性
  3. 指定格式字符串类型（邮箱、uuid、日期时间）
  4. 添加示例到复杂Schema
  5. 标记必填字段

Example

示例

yaml
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: "user@example.com"
        createdAt:
          type: string
          format: date-time
          description: Account creation timestamp
yaml
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: "user@example.com"
        createdAt:
          type: string
          format: date-time
          description: Account creation timestamp

Authentication Documentation

认证文档

Document auth requirements:
yaml
security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use your JWT token from /auth/login
编写认证要求：
yaml
security:
  - bearerAuth: []

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

Error Responses

错误响应

Standard error format:
yaml
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
Common HTTP status codes:
  • 200: Success
  • 201: Created
  • 204: No Content
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 409: Conflict
  • 422: Unprocessable Entity
  • 500: Internal Server Error
标准错误格式：
yaml
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: 服务器内部错误

Scripts

脚本

Generate OpenAPI spec from code:
bash
python scripts/generate_openapi.py
Validate OpenAPI spec:
bash
python scripts/validate_openapi.py openapi.yaml
从代码生成OpenAPI规范：
bash
python scripts/generate_openapi.py
验证OpenAPI规范：
bash
python scripts/validate_openapi.py openapi.yaml

References

参考资料

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