Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Update swagger docs #7710

Merged
merged 1 commit into from
Jan 13, 2025
+379 −121
Merged

feat: Update swagger docs #7710

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions backend/app/api/v1/backup.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The given code differs slightly in terms of comments regarding the success responses for both /settings/backup/record/size and /settings/backup/record/size/bycronjob. Both methods indicate a successful response with an array of dto.BackupFile, but there is no significant change beyond this detail.

To streamline the documentation, you could consider merging these two entries into one to ensure consistency:

@@ -166,7 +166,7 @@
 // @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 @@
 // @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/bac‌​​kup/record/size/bycronjob [post]

If the intent was to highlight that both endpoints return the same type of data (an array of dto.BackupFile), you might also want to mention that in the first comment under each route. However, if they indeed differ, it's worth noting that this is consistent with the current implementation.

Expand Down
187 changes: 143 additions & 44 deletions cmd/server/docs/docs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -19448,7 +19544,10 @@ const docTemplate = `{
"zh",
"en",
"tw",
"ru"
"ja",
"ru",
"ms",
"pt-BR"
]
},
"name": {
Expand Down Expand Up @@ -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"
}
}
}
},
Expand Down Expand Up @@ -24965,7 +25064,7 @@ const docTemplate = `{
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/response.AppDto"
"$ref": "#/definitions/response.AppItem"
}
},
"total": {
Expand Down Expand Up @@ -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"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Differences

  1. New Endpoint:

    • Added two new endpoints under the /settings/backup/record path: 
      "/settings/backup/record/size"
      and 
      "/settings/backup/record/size/bycronjob"

  2. Data Models and Responses:

    • Defined three data models (dto.BackupFile, response.AppInstalledCheck) that include fields like id, name, and size.
    • Updated existing responses to use these new models.

  3. Security Definitions:

    • Added a comment to clarify the custom token format used for authentication in various headers (including the one added).

  4. Schema References Update:

    • Fixed typo for the AppDto schema reference.
    • Ensured consistency with naming conventions (AppInstalledCheck vs. AppItem).

  5. Comments in Security Definition:

    • Corrected an error in the comments describing how to authenticate requests, including correct HTTP methods (GET instead of POST).

Overall, the changes enhance the clarity and maintainability of the API documentation by introducing new functionality related to backup record sizes and improving schema definitions. The updated security definition ensures proper handling of API keys across different routes.

Expand Down
Loading
Loading