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
This commit is contained in:
mac
+525
-19
@@ -17,6 +17,357 @@
|
||||
},
|
||||
"basePath": "/api/v1",
|
||||
"paths": {
|
||||
"/auth/api/v1/delivery/mysql": {
|
||||
"post": {
|
||||
"security": [
|
||||
{
|
||||
"BearerAuth": []
|
||||
}
|
||||
],
|
||||
"description": "创建一个 MySQL 交付任务，调度器会自动分配主机、调用 AWX 执行部署",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"delivery"
|
||||
],
|
||||
"summary": "提交 MySQL 一键交付",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "幂等键（防重复提交，最长 128 字符）",
|
||||
"name": "Idempotency-Key",
|
||||
"in": "header",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"description": "交付参数",
|
||||
"name": "body",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/service.MySQLDeliveryInput"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "幂等重放（相同 Idempotency-Key 已存在）",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"202": {
|
||||
"description": "任务已创建",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "参数错误",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未授权",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/auth/api/v1/delivery/quotas": {
|
||||
"put": {
|
||||
"security": [
|
||||
{
|
||||
"BearerAuth": []
|
||||
}
|
||||
],
|
||||
"description": "管理员为指定业务线 + 部署目标设置资源配额",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"delivery"
|
||||
],
|
||||
"summary": "创建或更新资源配额",
|
||||
"parameters": [
|
||||
{
|
||||
"description": "配额参数",
|
||||
"name": "body",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/handler.quotaPayload"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "配额已更新",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/model.ResourceQuota"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "参数错误",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未授权",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/auth/api/v1/delivery/targets": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"BearerAuth": []
|
||||
}
|
||||
],
|
||||
"description": "返回所有已启用的部署目标（如 k8s 集群、主机池）",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"delivery"
|
||||
],
|
||||
"summary": "获取可用部署目标",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "items: 部署目标数组",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "内部错误",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"security": [
|
||||
{
|
||||
"BearerAuth": []
|
||||
}
|
||||
],
|
||||
"description": "管理员创建新的部署目标（目前仅支持 k8s 类型）",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"delivery"
|
||||
],
|
||||
"summary": "创建部署目标",
|
||||
"parameters": [
|
||||
{
|
||||
"description": "目标配置",
|
||||
"name": "body",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/handler.targetPayload"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"201": {
|
||||
"description": "目标已创建",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/model.DeploymentTarget"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "参数错误",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未授权",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "名称冲突",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/auth/api/v1/delivery/tasks": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"BearerAuth": []
|
||||
}
|
||||
],
|
||||
"description": "返回当前用户可见的交付任务列表（管理员可见全部）",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"delivery"
|
||||
],
|
||||
"summary": "获取交付任务列表",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "业务线 ID 过滤",
|
||||
"name": "business_line_id",
|
||||
"in": "query"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "items: 任务数组",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未授权",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/auth/api/v1/delivery/tasks/{id}": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"BearerAuth": []
|
||||
}
|
||||
],
|
||||
"description": "返回指定任务的详细信息及事件流",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"delivery"
|
||||
],
|
||||
"summary": "获取交付任务详情",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "任务 ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "task + events",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未授权",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "任务不存在",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/auth/api/v1/delivery/tasks/{id}/cancel": {
|
||||
"post": {
|
||||
"security": [
|
||||
{
|
||||
"BearerAuth": []
|
||||
}
|
||||
],
|
||||
"description": "取消一个正在执行或等待中的交付任务",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"delivery"
|
||||
],
|
||||
"summary": "取消交付任务",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "任务 ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "ok: true",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未授权",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "无法取消（状态冲突）",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/ping": {
|
||||
"get": {
|
||||
"description": "检查服务器是否正常运行",
|
||||
@@ -36,7 +387,7 @@
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/handler.Response"
|
||||
"$ref": "#/definitions/response.Response"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
@@ -74,7 +425,7 @@
|
||||
"401": {
|
||||
"description": "Unauthorized",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/handler.Response"
|
||||
"$ref": "#/definitions/response.Response"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -97,7 +448,7 @@
|
||||
"403": {
|
||||
"description": "Forbidden",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/handler.Response"
|
||||
"$ref": "#/definitions/response.Response"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -120,7 +471,7 @@
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/handler.Response"
|
||||
"$ref": "#/definitions/response.Response"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -154,7 +505,7 @@
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/handler.Response"
|
||||
"$ref": "#/definitions/response.Response"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
@@ -170,7 +521,7 @@
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/handler.Response"
|
||||
"$ref": "#/definitions/response.Response"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -195,7 +546,7 @@
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/handler.Response"
|
||||
"$ref": "#/definitions/response.Response"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
@@ -203,7 +554,7 @@
|
||||
"data": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/handler.PaginatedData"
|
||||
"$ref": "#/definitions/response.PaginatedData"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
@@ -245,7 +596,7 @@
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/handler.Response"
|
||||
"$ref": "#/definitions/response.Response"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
@@ -286,13 +637,13 @@
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -300,7 +651,129 @@
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"handler.PaginatedData": {
|
||||
"handler.quotaPayload": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"business_line_id",
|
||||
"cpu_milli",
|
||||
"instance_limit",
|
||||
"memory_mi",
|
||||
"storage_gi",
|
||||
"target_id"
|
||||
],
|
||||
"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"
|
||||
}
|
||||
}
|
||||
},
|
||||
"handler.targetPayload": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"awx_inventory_id",
|
||||
"awx_template_id",
|
||||
"name",
|
||||
"target_type"
|
||||
],
|
||||
"properties": {
|
||||
"awx_inventory_id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"awx_template_id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"additionalProperties": {}
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"target_type": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"model.DeploymentTarget": {
|
||||
"type": "object",
|
||||
"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"
|
||||
}
|
||||
}
|
||||
},
|
||||
"model.ResourceQuota": {
|
||||
"type": "object",
|
||||
"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"
|
||||
}
|
||||
}
|
||||
},
|
||||
"response.PaginatedData": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"items": {},
|
||||
@@ -309,25 +782,58 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"handler.Response": {
|
||||
"response.Response": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"description": "业务错误码，0 表示成功",
|
||||
"type": "integer"
|
||||
},
|
||||
"data": {
|
||||
"description": "响应数据，成功时返回"
|
||||
},
|
||||
"data": {},
|
||||
"details": {
|
||||
"description": "错误详情，失败时返回",
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"description": "响应消息",
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"service.MySQLDeliveryInput": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"business_line_id",
|
||||
"cpu_milli",
|
||||
"instance_name",
|
||||
"memory_mi",
|
||||
"namespace",
|
||||
"storage_gi",
|
||||
"target_id"
|
||||
],
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"securityDefinitions": {
|
||||
|
||||
Reference in New Issue
Block a user