swagger-doc-writer

name	swagger-doc-writer
description	Generates Swagger 2.0 YAML for HTTP endpoints from an interface specification. Produces a validator-ready skeleton (info/host/basePath/schemes/consumes/produces/paths/definitions/securityDefinitions) with reusable ErrorResponse / paging / auth defaults. Use when the user asks to write or scaffold a Swagger doc / API spec for an HTTP endpoint.

Swagger Doc Writer (Swagger 2.0)

When To Use

Use when the user asks to produce a Swagger 2.0 spec for an HTTP API — either for a new endpoint or when documenting an existing endpoint that has no spec yet.

触发短语：

• "为 xxx 接口写 swagger 文档 / API spec"
• "scaffold swagger for GET /models/:name"
• "生成 swagger 2.0 骨架"
• "把这个 handler 的接口转成 swagger"

如果用户给的是已有 YAML 让你修复/校验，请改用 swagger-doc-validator。

必会知识域（Swagger 2.0）

1. Version & global: swagger: "2.0", info{title, version, description, contact?, license?}
2. Base URL: host, basePath, schemes（所有 paths 相对 base URL）
3. MIME: 根级 consumes/produces，operation 级可覆盖
4. Paths & operations: 每个 operation 必备 responses；推荐 operationId, tags, summary
5. Parameters: in ∈ {path,query,header,body,formData}；
   • in: path 必须 required: true，name 必须匹配 {xxx}
   • in: body 必须使用 schema:（不是 type:），且通常 $ref 到 definitions
6. Responses: 每个状态码必须带 description；响应体用 schema 或 $ref；可加 default 兜底
7. Definitions: 重复结构用 $ref: "#/definitions/<Name>" 复用
8. Auth: securityDefinitions 覆盖 basic / apiKey(header|query) / oauth2(implicit|password|application|accessCode)；security 引用这些 scheme

Workflow

1. 收集接口契约（缺什么问什么）：
   • 方法 + 路径（含 {id} path params）
   • 请求参数：位置、类型、是否必填、枚举/默认值
   • 请求体 schema（可复用现有 CRD/结构体字段，贴 ieops-v2 API 风格）
   • 响应状态码集合与响应体 schema
   • 错误码覆盖（默认 400/401/403/404/409/500，按需加 429）
   • 鉴权要求
2. 先全局后局部输出：
   1. swagger/info/host/basePath/schemes/consumes/produces
   2. securityDefinitions（若启用）+ 全局 security 或 operation 级 security
   3. 逐条 paths 下 operation（参数 → responses → 指向 definitions）
   4. 抽象 definitions，修正 $ref
3. 默认落地规则（强制）：
   • 所有 responses[status] 必须有 description
   • /x/{id} 在 parameters 必须出现 in: path, name: id, required: true
   • in: body 必须用 schema:
   • 错误响应至少覆盖 400/401/403/404/500，全部 $ref: #/definitions/ErrorResponse
   • 无鉴权：删除或不加 security，避免误导
4. 落盘位置：默认只打印 YAML 给用户 review；若用户让你写文件：
   • 过程材料 → .cursor/plans/swagger-<service>-<date>.yaml
   • 正式产物 → docs/reference/api/<service>.yaml（需用户确认）
5. 最后建议用户用 swagger-doc-validator skill 再跑一遍校验。

YAML 模板骨架（可直接填充）

swagger: "2.0"
info:
  title: __SERVICE_NAME__           # e.g. ieops-v2 BFF
  description: __SERVICE_DESCRIPTION__
  version: __SERVICE_VERSION__      # e.g. v1alpha1
  contact:
    name: __CONTACT_NAME__
    email: __CONTACT_EMAIL__

host: __HOST__                      # e.g. bff.ieops.example.com (占位即可)
basePath: /api/v1                   # API 路由前缀（按实际修改）
schemes:
  - https

consumes:
  - application/json
produces:
  - application/json

# 启用时填，否则删掉
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: __API_KEY_HEADER__        # e.g. X-API-Key
# security:
#   - ApiKeyAuth: []

paths:
  /__RESOURCE__:
    get:
      summary: __SUMMARY__
      operationId: __OPERATION_ID__
      tags: [__TAG__]
      parameters:
        - in: query
          name: limit
          type: integer
          required: false
          format: int32
          minimum: 1
          maximum: 1000
          default: 20
          description: 返回的最大数量
      responses:
        "200":
          description: 成功返回 __DESCRIPTION__
          schema:
            $ref: "#/definitions/__RESPONSE_WRAPPER__"
        "400": { description: 参数错误,   schema: { $ref: "#/definitions/ErrorResponse" } }
        "401": { description: 未认证,     schema: { $ref: "#/definitions/ErrorResponse" } }
        "403": { description: 权限不足,   schema: { $ref: "#/definitions/ErrorResponse" } }
        "404": { description: 资源不存在, schema: { $ref: "#/definitions/ErrorResponse" } }
        "500": { description: 服务器内部错误, schema: { $ref: "#/definitions/ErrorResponse" } }

  /__RESOURCE__/{__ID__}:
    get:
      summary: __SUMMARY__
      operationId: __OPERATION_ID__
      tags: [__TAG__]
      parameters:
        - in: path
          name: __ID__                # 必须与 {__ID__} 一致
          type: string
          required: true
          description: __ID_DESC__
      responses:
        "200": { description: 成功, schema: { $ref: "#/definitions/__RESPONSE_MODEL__" } }
        "400": { description: 参数错误,   schema: { $ref: "#/definitions/ErrorResponse" } }
        "404": { description: 未找到,     schema: { $ref: "#/definitions/ErrorResponse" } }
        "500": { description: 服务器内部错误, schema: { $ref: "#/definitions/ErrorResponse" } }

definitions:
  ErrorResponse:
    type: object
    required: [code, message, requestId]
    properties:
      code:      { type: string, example: INVALID_ARGUMENT }
      message:   { type: string, example: "参数不合法" }
      requestId: { type: string, example: "req_123456" }
      details:
        type: object
        additionalProperties: true

  PageMetadata:
    type: object
    required: [limit, offset, total]
    properties:
      limit:  { type: integer, format: int32, example: 20 }
      offset: { type: integer, format: int32, example: 0 }
      total:  { type: integer, format: int64, example: 123 }

  # 具体模型按接口填充
  __RESPONSE_MODEL__:
    type: object
    required: [__FIELD_1__]
    properties:
      __FIELD_1__: { type: string, example: __EXAMPLE__ }
      created_at:  { type: string, format: date-time, example: "2026-04-23T12:34:56Z" }

Output Checklist

• swagger: "2.0" + info.title/version + basePath: /api/v1
• 每个 operation 有 responses，所有状态码都有 description
• 错误响应统一 $ref: #/definitions/ErrorResponse
• in: path 参数 required: true 且 name 与 {} 匹配
• in: body 使用 schema:（不是 type:）
• 所有 $ref 指向存在的 definition
• 鉴权：要么完整 securityDefinitions + security，要么都不填；不要半填
• 生成完提醒用户用 swagger-doc-validator 跑一次

Additional Resources

• Trigger phrases 与完整 I/O 示例：examples.md
• 相关 skill：swagger-doc-validator（校验/纠错）