xinfra/server/docs/swagger.yaml

basePath: /api/v1
definitions:
  handler.quotaPayload:
    properties:
      business_line_id:
        type: integer
      cpu_milli:
        type: integer
      instance_limit:
        type: integer
      memory_mi:
        type: integer
      storage_gi:
        type: integer
      target_id:
        type: integer
    required:
    - business_line_id
    - cpu_milli
    - instance_limit
    - memory_mi
    - storage_gi
    - target_id
    type: object
  model.ResourceQuota:
    properties:
      business_line_id:
        type: integer
      cpu_milli:
        type: integer
      created_at:
        type: string
      id:
        type: integer
      instance_limit:
        type: integer
      memory_mi:
        type: integer
      storage_gi:
        type: integer
      target_id:
        type: integer
      updated_at:
        type: string
    type: object
  response.PaginatedData:
    properties:
      items: {}
      total:
        type: integer
    type: object
  response.Response:
    properties:
      code:
        type: integer
      data: {}
      details:
        type: string
      message:
        type: string
    type: object
  service.MySQLDeliveryInput:
    properties:
      binlog_expire_logs_seconds:
        type: integer
      business_line_id:
        type: integer
      character_set:
        type: string
      collation:
        type: string
      cpu_milli:
        type: integer
      data_disk:
        type: string
      innodb_flush_log_at_trx_commit:
        type: integer
      innodb_io_capacity:
        type: integer
      innodb_redo_log_capacity:
        type: string
      instance_name:
        type: string
      long_query_time:
        type: number
      lower_case_table_names:
        type: integer
      max_binlog_size:
        type: string
      max_connections:
        description: 高级参数（选填，零值视为未设置）
        type: string
      memory_mi:
        type: integer
      mysql_port:
        type: integer
      mysql_version:
        type: string
      namespace:
        type: string
      storage_gi:
        type: integer
      sync_binlog:
        type: integer
      target_host:
        description: 调度控制（选填）：点名候选池内主机跳过自动选机，端口/配额/实机守卫照常执行
        type: string
      target_id:
        type: integer
      timezone:
        description: 数据库配置（选填，缺省由 playbook 基线兜底）
        type: string
      topology:
        type: string
    required:
    - business_line_id
    - cpu_milli
    - instance_name
    - memory_mi
    - namespace
    - storage_gi
    - target_id
    type: object
info:
  contact:
    email: support@swagger.io
    name: API Support
    url: http://www.swagger.io/support
  description: xinfra 平台后端 API 文档
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://swagger.io/terms/
  title: xinfra API
  version: "1.0"
paths:
  /auth/api/v1/delivery/mysql:
    post:
      consumes:
      - application/json
      description: 创建一个 MySQL 交付任务，调度器会自动分配主机、调用 AWX 执行部署
      parameters:
      - description: 幂等键（防重复提交，最长 128 字符）
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 交付参数
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/service.MySQLDeliveryInput'
      produces:
      - application/json
      responses:
        "200":
          description: 幂等重放（相同 Idempotency-Key 已存在）
          schema:
            additionalProperties: true
            type: object
        "202":
          description: 任务已创建
          schema:
            additionalProperties: true
            type: object
        "400":
          description: 参数错误
          schema:
            additionalProperties: true
            type: object
        "401":
          description: 未授权
          schema:
            additionalProperties: true
            type: object
      security:
      - BearerAuth: []
      summary: 提交 MySQL 一键交付
      tags:
      - delivery
  /auth/api/v1/delivery/quotas:
    put:
      consumes:
      - application/json
      description: 管理员为指定业务线 + 部署目标设置资源配额
      parameters:
      - description: 配额参数
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handler.quotaPayload'
      produces:
      - application/json
      responses:
        "200":
          description: 配额已更新
          schema:
            $ref: '#/definitions/model.ResourceQuota'
        "400":
          description: 参数错误
          schema:
            additionalProperties: true
            type: object
        "401":
          description: 未授权
          schema:
            additionalProperties: true
            type: object
      security:
      - BearerAuth: []
      summary: 创建或更新资源配额
      tags:
      - delivery
  /auth/api/v1/delivery/targets:
    get:
      description: 从 AWX 动态返回可用 Job Template 及其 Inventory hosts
      parameters:
      - description: 组件过滤，例如 mysql
        in: query
        name: component
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 'items: 部署目标数组'
          schema:
            additionalProperties: true
            type: object
        "500":
          description: 内部错误
          schema:
            additionalProperties: true
            type: object
      security:
      - BearerAuth: []
      summary: 获取可用部署目标
      tags:
      - delivery
  /auth/api/v1/delivery/tasks:
    get:
      description: 返回当前用户可见的交付任务列表（管理员可见全部）
      parameters:
      - description: 业务线 ID 过滤
        format: int64
        in: query
        name: business_line_id
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 'items: 任务数组'
          schema:
            additionalProperties: true
            type: object
        "401":
          description: 未授权
          schema:
            additionalProperties: true
            type: object
      security:
      - BearerAuth: []
      summary: 获取交付任务列表
      tags:
      - delivery
  /auth/api/v1/delivery/tasks/{id}:
    get:
      description: 返回指定任务的详细信息及事件流
      parameters:
      - description: 任务 ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: task + events
          schema:
            additionalProperties: true
            type: object
        "401":
          description: 未授权
          schema:
            additionalProperties: true
            type: object
        "404":
          description: 任务不存在
          schema:
            additionalProperties: true
            type: object
      security:
      - BearerAuth: []
      summary: 获取交付任务详情
      tags:
      - delivery
  /auth/api/v1/delivery/tasks/{id}/cancel:
    post:
      description: 取消一个正在执行或等待中的交付任务
      parameters:
      - description: 任务 ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 'ok: true'
          schema:
            additionalProperties: true
            type: object
        "401":
          description: 未授权
          schema:
            additionalProperties: true
            type: object
        "409":
          description: 无法取消（状态冲突）
          schema:
            additionalProperties: true
            type: object
      security:
      - BearerAuth: []
      summary: 取消交付任务
      tags:
      - delivery
  /ping:
    get:
      consumes:
      - application/json
      description: 检查服务器是否正常运行
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  properties:
                    time:
                      type: string
                  type: object
              type: object
      summary: 健康检查
      tags:
      - 系统
  /test/401:
    get:
      consumes:
      - application/json
      description: 模拟返回 HTTP 401 未授权错误
      produces:
      - application/json
      responses:
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/response.Response'
      summary: 测试 401 错误
      tags:
      - 测试
  /test/403:
    get:
      consumes:
      - application/json
      description: 模拟返回 HTTP 403 禁止访问错误
      produces:
      - application/json
      responses:
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/response.Response'
      summary: 测试 403 错误
      tags:
      - 测试
  /test/500:
    get:
      consumes:
      - application/json
      description: 模拟返回 HTTP 500 服务器内部错误
      produces:
      - application/json
      responses:
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/response.Response'
      summary: 测试 500 错误
      tags:
      - 测试
  /test/error/{code}:
    get:
      consumes:
      - application/json
      description: 根据错误码返回对应的业务错误响应
      parameters:
      - description: '业务错误码 (10001-10099: 认证相关, 20001-20099: 任务相关)'
        in: path
        name: code
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                details:
                  type: string
              type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/response.Response'
      summary: 测试业务错误响应
      tags:
      - 测试
  /test/paginated:
    get:
      consumes:
      - application/json
      description: 测试返回分页数据的统一响应格式
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  allOf:
                  - $ref: '#/definitions/response.PaginatedData'
                  - properties:
                      items:
                        items:
                          type: object
                        type: array
                    type: object
              type: object
      summary: 测试分页响应
      tags:
      - 测试
  /test/success:
    get:
      consumes:
      - application/json
      description: 测试返回成功的统一响应格式
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  properties:
                    role:
                      type: string
                    username:
                      type: string
                  type: object
              type: object
      summary: 测试成功响应
      tags:
      - 测试
  /test/timeout:
    get:
      consumes:
      - application/json
      description: 模拟请求超时（15秒延迟，超过前端 10s timeout）
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
        "408":
          description: Request Timeout
          schema:
            $ref: '#/definitions/response.Response'
      summary: 测试超时响应
      tags:
      - 测试
securityDefinitions:
  BearerAuth:
    description: 请输入 Bearer Token（例如：Bearer xxx）
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"