docs(delivery): add Swagger annotations and regenerate API docs

Add Swagger annotations to all 7 delivery handlers. Fix existing test.go type references (Response -> response.Response). Add swaggo dependencies to go.mod. Regenerate swagger.json/yaml/docs.go with delivery endpoints visible in /swagger/index.html. Relates-to: #97
2026-07-23 12:05:21 +08:00
parent 5ddb434b74
commit c421be3ae9
6 changed files with 1429 additions and 66 deletions
@@ -1,25 +1,131 @@
 basePath: /api/v1
 definitions:
-  handler.PaginatedData:
+  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
+  handler.targetPayload:
+    properties:
+      awx_inventory_id:
+        type: integer
+      awx_template_id:
+        type: integer
+      metadata:
+        additionalProperties: {}
+        type: object
+      name:
+        type: string
+      target_type:
+        type: string
+    required:
+    - awx_inventory_id
+    - awx_template_id
+    - name
+    - target_type
+    type: object
+  model.DeploymentTarget:
+    properties:
+      awx_inventory_id:
+        type: integer
+      awx_template_id:
+        type: integer
+      created_at:
+        type: string
+      enabled:
+        type: boolean
+      id:
+        type: integer
+      metadata:
+        type: string
+      name:
+        type: string
+      target_type:
+        type: string
+      updated_at:
+        type: string
+    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
-  handler.Response:
+  response.Response:
    properties:
      code:
-        description: 业务错误码，0 表示成功
        type: integer
-      data:
-        description: 响应数据，成功时返回
+      data: {}
      details:
-        description: 错误详情，失败时返回
        type: string
      message:
-        description: 响应消息
        type: string
    type: object
+  service.MySQLDeliveryInput:
+    properties:
+      business_line_id:
+        type: integer
+      cpu_milli:
+        type: integer
+      instance_name:
+        type: string
+      memory_mi:
+        type: integer
+      mysql_version:
+        type: string
+      namespace:
+        type: string
+      storage_gi:
+        type: integer
+      target_id:
+        type: integer
+    required:
+    - business_line_id
+    - cpu_milli
+    - instance_name
+    - memory_mi
+    - namespace
+    - storage_gi
+    - target_id
+    type: object
 info:
  contact:
    email: support@swagger.io
@@ -33,6 +139,234 @@ info:
  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: 返回所有已启用的部署目标（如 k8s 集群、主机池）
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 'items: 部署目标数组'
+          schema:
+            additionalProperties: true
+            type: object
+        "500":
+          description: 内部错误
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 获取可用部署目标
+      tags:
+      - delivery
+    post:
+      consumes:
+      - application/json
+      description: 管理员创建新的部署目标（目前仅支持 k8s 类型）
+      parameters:
+      - description: 目标配置
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/handler.targetPayload'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: 目标已创建
+          schema:
+            $ref: '#/definitions/model.DeploymentTarget'
+        "400":
+          description: 参数错误
+          schema:
+            additionalProperties: true
+            type: object
+        "401":
+          description: 未授权
+          schema:
+            additionalProperties: true
+            type: object
+        "409":
+          description: 名称冲突
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 创建部署目标
+      tags:
+      - delivery
+  /auth/api/v1/delivery/tasks:
+    get:
+      description: 返回当前用户可见的交付任务列表（管理员可见全部）
+      parameters:
+      - description: 业务线 ID 过滤
+        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:
@@ -45,7 +379,7 @@ paths:
          description: OK
          schema:
            allOf:
-            - $ref: '#/definitions/handler.Response'
+            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  properties:
@@ -67,7 +401,7 @@ paths:
        "401":
          description: Unauthorized
          schema:
-            $ref: '#/definitions/handler.Response'
+            $ref: '#/definitions/response.Response'
      summary: 测试 401 错误
      tags:
      - 测试
@@ -82,7 +416,7 @@ paths:
        "403":
          description: Forbidden
          schema:
-            $ref: '#/definitions/handler.Response'
+            $ref: '#/definitions/response.Response'
      summary: 测试 403 错误
      tags:
      - 测试
@@ -97,7 +431,7 @@ paths:
        "500":
          description: Internal Server Error
          schema:
-            $ref: '#/definitions/handler.Response'
+            $ref: '#/definitions/response.Response'
      summary: 测试 500 错误
      tags:
      - 测试
@@ -119,7 +453,7 @@ paths:
          description: OK
          schema:
            allOf:
-            - $ref: '#/definitions/handler.Response'
+            - $ref: '#/definitions/response.Response'
            - properties:
                details:
                  type: string
@@ -127,7 +461,7 @@ paths:
        "400":
          description: Bad Request
          schema:
-            $ref: '#/definitions/handler.Response'
+            $ref: '#/definitions/response.Response'
      summary: 测试业务错误响应
      tags:
      - 测试
@@ -143,11 +477,11 @@ paths:
          description: OK
          schema:
            allOf:
-            - $ref: '#/definitions/handler.Response'
+            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  allOf:
-                  - $ref: '#/definitions/handler.PaginatedData'
+                  - $ref: '#/definitions/response.PaginatedData'
                  - properties:
                      items:
                        items:
@@ -170,7 +504,7 @@ paths:
          description: OK
          schema:
            allOf:
-            - $ref: '#/definitions/handler.Response'
+            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  properties:
@@ -194,11 +528,11 @@ paths:
        "200":
          description: OK
          schema:
-            $ref: '#/definitions/handler.Response'
+            $ref: '#/definitions/response.Response'
        "408":
          description: Request Timeout
          schema:
-            $ref: '#/definitions/handler.Response'
+            $ref: '#/definitions/response.Response'
      summary: 测试超时响应
      tags:
      - 测试