From 999e5a779a42fbe8170bae40cdd8592df05d7805 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=98=AD?= <81747598+lan-yonghui@users.noreply.github.com> Date: Mon, 13 Jan 2025 23:10:04 +0800 Subject: [PATCH] feat: Update swagger docs (#7710) --- backend/app/api/v1/backup.go | 4 +- cmd/server/docs/docs.go | 187 ++++++++++++++++++++++++++--------- cmd/server/docs/swagger.json | 187 ++++++++++++++++++++++++++--------- cmd/server/docs/swagger.yaml | 120 ++++++++++++++++------ cmd/server/main.go | 2 +- 5 files changed, 379 insertions(+), 121 deletions(-) diff --git a/backend/app/api/v1/backup.go b/backend/app/api/v1/backup.go index f10c8dc64d54..acd7dc210d5e 100644 --- a/backend/app/api/v1/backup.go +++ b/backend/app/api/v1/backup.go @@ -166,7 +166,7 @@ func (b *BaseApi) SearchBackupRecords(c *gin.Context) { // @Summary Load backup records size // @Accept json // @Param request body dto.RecordSearch true "request" -// @Success 200 {array} dto.dto.BackupFile +// @Success 200 {array} dto.BackupFile // @Security ApiKeyAuth // @Security Timestamp // @Router /settings/backup/record/size [post] @@ -215,7 +215,7 @@ func (b *BaseApi) SearchBackupRecordsByCronjob(c *gin.Context) { // @Summary Load backup records size for cronjob // @Accept json // @Param request body dto.RecordSearchByCronjob true "request" -// @Success 200 {array} dto.dto.BackupFile +// @Success 200 {array} dto.BackupFile // @Security ApiKeyAuth // @Security Timestamp // @Router /settings/backup/record/size/bycronjob [post] diff --git a/cmd/server/docs/docs.go b/cmd/server/docs/docs.go index 64baf6502910..eec0c548537d 100644 --- a/cmd/server/docs/docs.go +++ b/cmd/server/docs/docs.go @@ -10624,6 +10624,88 @@ const docTemplate = `{ } } }, + "/settings/backup/record/size": { + "post": { + "security": [ + { + "ApiKeyAuth": [] + }, + { + "Timestamp": [] + } + ], + "consumes": [ + "application/json" + ], + "tags": [ + "Backup Account" + ], + "summary": "Load backup records size", + "parameters": [ + { + "description": "request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.RecordSearch" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.BackupFile" + } + } + } + } + } + }, + "/settings/backup/record/size/bycronjob": { + "post": { + "security": [ + { + "ApiKeyAuth": [] + }, + { + "Timestamp": [] + } + ], + "consumes": [ + "application/json" + ], + "tags": [ + "Backup Account" + ], + "summary": "Load backup records size for cronjob", + "parameters": [ + { + "description": "request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.RecordSearchByCronjob" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.BackupFile" + } + } + } + } + } + }, "/settings/backup/recover": { "post": { "security": [ @@ -16684,6 +16766,20 @@ const docTemplate = `{ } } }, + "dto.BackupFile": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "size": { + "type": "integer" + } + } + }, "dto.BackupInfo": { "type": "object", "properties": { @@ -19448,7 +19544,10 @@ const docTemplate = `{ "zh", "en", "tw", - "ru" + "ja", + "ru", + "ms", + "pt-BR" ] }, "name": { @@ -24834,94 +24933,94 @@ const docTemplate = `{ } } }, - "response.AppDto": { + "response.AppInstalledCheck": { "type": "object", "properties": { - "icon": { + "app": { "type": "string" }, - "id": { + "appInstallId": { "type": "integer" }, - "installed": { - "type": "boolean" + "containerName": { + "type": "string" }, - "key": { + "createdAt": { "type": "string" }, - "limit": { + "httpPort": { "type": "integer" }, - "name": { - "type": "string" + "httpsPort": { + "type": "integer" }, - "resource": { + "installPath": { "type": "string" }, - "shortDescEn": { + "isExist": { + "type": "boolean" + }, + "lastBackupAt": { "type": "string" }, - "shortDescZh": { + "name": { "type": "string" }, "status": { "type": "string" }, - "tags": { - "type": "array", - "items": { - "$ref": "#/definitions/model.Tag" - } - }, - "type": { + "version": { "type": "string" - }, - "versions": { - "type": "array", - "items": { - "type": "string" - } } } }, - "response.AppInstalledCheck": { + "response.AppItem": { "type": "object", "properties": { - "app": { + "icon": { "type": "string" }, - "appInstallId": { + "id": { "type": "integer" }, - "containerName": { - "type": "string" + "installed": { + "type": "boolean" }, - "createdAt": { + "key": { "type": "string" }, - "httpPort": { - "type": "integer" - }, - "httpsPort": { + "limit": { "type": "integer" }, - "installPath": { + "name": { "type": "string" }, - "isExist": { - "type": "boolean" + "resource": { + "type": "string" }, - "lastBackupAt": { + "shortDescEn": { "type": "string" }, - "name": { + "shortDescZh": { "type": "string" }, "status": { "type": "string" }, - "version": { + "tags": { + "type": "array", + "items": { + "$ref": "#/definitions/model.Tag" + } + }, + "type": { "type": "string" + }, + "versions": { + "type": "array", + "items": { + "type": "string" + } } } }, @@ -24965,7 +25064,7 @@ const docTemplate = `{ "items": { "type": "array", "items": { - "$ref": "#/definitions/response.AppDto" + "$ref": "#/definitions/response.AppItem" } }, "total": { @@ -25965,7 +26064,7 @@ const docTemplate = `{ }, "securityDefinitions": { "ApiKeyAuth": { - "description": "Custom Token Format, Format: md5('1panel' + API-Key + UnixTimestamp).\n` + "`" + `` + "`" + `` + "`" + `\neg:\ncurl -X GET \"http://localhost:4004/api/v1/resource\" \\\n-H \"1Panel-Token: \u003c1panel_token\u003e\" \\\n-H \"1Panel-Timestamp: \u003ccurrent_unix_timestamp\u003e\"\n` + "`" + `` + "`" + `` + "`" + `\n- ` + "`" + `1Panel-Token` + "`" + ` is the key for the panel API Key.", + "description": "Custom Token Format, Format: md5('1panel' + API-Key + UnixTimestamp).\n` + "`" + `` + "`" + `` + "`" + `\neg:\ncurl -X GET \"http://localhost:4004/api/v1/dashboard/current\" \\\n-H \"1Panel-Token: \u003c1panel_token\u003e\" \\\n-H \"1Panel-Timestamp: \u003ccurrent_unix_timestamp\u003e\"\n` + "`" + `` + "`" + `` + "`" + `\n- ` + "`" + `1Panel-Token` + "`" + ` is the key for the panel API Key.", "type": "apiKey", "name": "1Panel-Token", "in": "header" diff --git a/cmd/server/docs/swagger.json b/cmd/server/docs/swagger.json index 75306f5cde10..6ef34082c2bd 100644 --- a/cmd/server/docs/swagger.json +++ b/cmd/server/docs/swagger.json @@ -10621,6 +10621,88 @@ } } }, + "/settings/backup/record/size": { + "post": { + "security": [ + { + "ApiKeyAuth": [] + }, + { + "Timestamp": [] + } + ], + "consumes": [ + "application/json" + ], + "tags": [ + "Backup Account" + ], + "summary": "Load backup records size", + "parameters": [ + { + "description": "request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.RecordSearch" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.BackupFile" + } + } + } + } + } + }, + "/settings/backup/record/size/bycronjob": { + "post": { + "security": [ + { + "ApiKeyAuth": [] + }, + { + "Timestamp": [] + } + ], + "consumes": [ + "application/json" + ], + "tags": [ + "Backup Account" + ], + "summary": "Load backup records size for cronjob", + "parameters": [ + { + "description": "request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.RecordSearchByCronjob" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/dto.BackupFile" + } + } + } + } + } + }, "/settings/backup/recover": { "post": { "security": [ @@ -16681,6 +16763,20 @@ } } }, + "dto.BackupFile": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "size": { + "type": "integer" + } + } + }, "dto.BackupInfo": { "type": "object", "properties": { @@ -19445,7 +19541,10 @@ "zh", "en", "tw", - "ru" + "ja", + "ru", + "ms", + "pt-BR" ] }, "name": { @@ -24831,94 +24930,94 @@ } } }, - "response.AppDto": { + "response.AppInstalledCheck": { "type": "object", "properties": { - "icon": { + "app": { "type": "string" }, - "id": { + "appInstallId": { "type": "integer" }, - "installed": { - "type": "boolean" + "containerName": { + "type": "string" }, - "key": { + "createdAt": { "type": "string" }, - "limit": { + "httpPort": { "type": "integer" }, - "name": { - "type": "string" + "httpsPort": { + "type": "integer" }, - "resource": { + "installPath": { "type": "string" }, - "shortDescEn": { + "isExist": { + "type": "boolean" + }, + "lastBackupAt": { "type": "string" }, - "shortDescZh": { + "name": { "type": "string" }, "status": { "type": "string" }, - "tags": { - "type": "array", - "items": { - "$ref": "#/definitions/model.Tag" - } - }, - "type": { + "version": { "type": "string" - }, - "versions": { - "type": "array", - "items": { - "type": "string" - } } } }, - "response.AppInstalledCheck": { + "response.AppItem": { "type": "object", "properties": { - "app": { + "icon": { "type": "string" }, - "appInstallId": { + "id": { "type": "integer" }, - "containerName": { - "type": "string" + "installed": { + "type": "boolean" }, - "createdAt": { + "key": { "type": "string" }, - "httpPort": { - "type": "integer" - }, - "httpsPort": { + "limit": { "type": "integer" }, - "installPath": { + "name": { "type": "string" }, - "isExist": { - "type": "boolean" + "resource": { + "type": "string" }, - "lastBackupAt": { + "shortDescEn": { "type": "string" }, - "name": { + "shortDescZh": { "type": "string" }, "status": { "type": "string" }, - "version": { + "tags": { + "type": "array", + "items": { + "$ref": "#/definitions/model.Tag" + } + }, + "type": { "type": "string" + }, + "versions": { + "type": "array", + "items": { + "type": "string" + } } } }, @@ -24962,7 +25061,7 @@ "items": { "type": "array", "items": { - "$ref": "#/definitions/response.AppDto" + "$ref": "#/definitions/response.AppItem" } }, "total": { @@ -25962,7 +26061,7 @@ }, "securityDefinitions": { "ApiKeyAuth": { - "description": "Custom Token Format, Format: md5('1panel' + API-Key + UnixTimestamp).\n```\neg:\ncurl -X GET \"http://localhost:4004/api/v1/resource\" \\\n-H \"1Panel-Token: \u003c1panel_token\u003e\" \\\n-H \"1Panel-Timestamp: \u003ccurrent_unix_timestamp\u003e\"\n```\n- `1Panel-Token` is the key for the panel API Key.", + "description": "Custom Token Format, Format: md5('1panel' + API-Key + UnixTimestamp).\n```\neg:\ncurl -X GET \"http://localhost:4004/api/v1/dashboard/current\" \\\n-H \"1Panel-Token: \u003c1panel_token\u003e\" \\\n-H \"1Panel-Timestamp: \u003ccurrent_unix_timestamp\u003e\"\n```\n- `1Panel-Token` is the key for the panel API Key.", "type": "apiKey", "name": "1Panel-Token", "in": "header" diff --git a/cmd/server/docs/swagger.yaml b/cmd/server/docs/swagger.yaml index 00c691dbdd09..cf37274cd279 100644 --- a/cmd/server/docs/swagger.yaml +++ b/cmd/server/docs/swagger.yaml @@ -145,6 +145,15 @@ definitions: version: type: string type: object + dto.BackupFile: + properties: + id: + type: integer + name: + type: string + size: + type: integer + type: object dto.BackupInfo: properties: backupPath: @@ -1999,7 +2008,10 @@ definitions: - zh - en - tw + - ja - ru + - ms + - pt-BR type: string name: type: string @@ -5627,7 +5639,34 @@ definitions: version: type: string type: object - response.AppDto: + response.AppInstalledCheck: + properties: + app: + type: string + appInstallId: + type: integer + containerName: + type: string + createdAt: + type: string + httpPort: + type: integer + httpsPort: + type: integer + installPath: + type: string + isExist: + type: boolean + lastBackupAt: + type: string + name: + type: string + status: + type: string + version: + type: string + type: object + response.AppItem: properties: icon: type: string @@ -5660,33 +5699,6 @@ definitions: type: string type: array type: object - response.AppInstalledCheck: - properties: - app: - type: string - appInstallId: - type: integer - containerName: - type: string - createdAt: - type: string - httpPort: - type: integer - httpsPort: - type: integer - installPath: - type: string - isExist: - type: boolean - lastBackupAt: - type: string - name: - type: string - status: - type: string - version: - type: string - type: object response.AppParam: properties: edit: @@ -5714,7 +5726,7 @@ definitions: properties: items: items: - $ref: '#/definitions/response.AppDto' + $ref: '#/definitions/response.AppItem' type: array total: type: integer @@ -12765,6 +12777,54 @@ paths: summary: Page backup records by cronjob tags: - Backup Account + /settings/backup/record/size: + post: + consumes: + - application/json + parameters: + - description: request + in: body + name: request + required: true + schema: + $ref: '#/definitions/dto.RecordSearch' + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/dto.BackupFile' + type: array + security: + - ApiKeyAuth: [] + - Timestamp: [] + summary: Load backup records size + tags: + - Backup Account + /settings/backup/record/size/bycronjob: + post: + consumes: + - application/json + parameters: + - description: request + in: body + name: request + required: true + schema: + $ref: '#/definitions/dto.RecordSearchByCronjob' + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/dto.BackupFile' + type: array + security: + - ApiKeyAuth: [] + - Timestamp: [] + summary: Load backup records size for cronjob + tags: + - Backup Account /settings/backup/recover: post: consumes: @@ -16303,7 +16363,7 @@ securityDefinitions: Custom Token Format, Format: md5('1panel' + API-Key + UnixTimestamp). ``` eg: - curl -X GET "http://localhost:4004/api/v1/resource" \ + curl -X GET "http://localhost:4004/api/v1/dashboard/current" \ -H "1Panel-Token: <1panel_token>" \ -H "1Panel-Timestamp: " ``` diff --git a/cmd/server/main.go b/cmd/server/main.go index 42d42b14c1ad..97a838d17a7c 100644 --- a/cmd/server/main.go +++ b/cmd/server/main.go @@ -23,7 +23,7 @@ import ( // @description Custom Token Format, Format: md5('1panel' + API-Key + UnixTimestamp). // @description ``` // @description eg: -// @description curl -X GET "http://localhost:4004/api/v1/resource" \ +// @description curl -X GET "http://localhost:4004/api/v1/dashboard/current" \ // @description -H "1Panel-Token: <1panel_token>" \ // @description -H "1Panel-Timestamp: " // @description ```