mac
c421be3ae9
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
546 lines
13 KiB
YAML
546 lines
13 KiB
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
|
||
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
|
||
response.Response:
|
||
properties:
|
||
code:
|
||
type: integer
|
||
data: {}
|
||
details:
|
||
type: string
|
||
message:
|
||
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
|
||
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: 返回所有已启用的部署目标（如 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:
|
||
- 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"
|