feat: Update swagger docs #7710
Conversation
|
Adding the "do-not-merge/release-note-label-needed" label because no release-note block was detected, please follow our release note process to remove it. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
| @@ -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" | |||
There was a problem hiding this comment.
Code Differences
-
New Endpoint:
- Added two new endpoints under the
/settings/backup/recordpath:and"/settings/backup/record/size""/settings/backup/record/size/bycronjob"
- Added two new endpoints under the
-
Data Models and Responses:
- Defined three data models (
dto.BackupFile,response.AppInstalledCheck) that include fields likeid,name, andsize. - Updated existing responses to use these new models.
- Defined three data models (
-
Security Definitions:
- Added a comment to clarify the custom token format used for authentication in various headers (including the one added).
-
Schema References Update:
- Fixed typo for the
AppDtoschema reference. - Ensured consistency with naming conventions (
AppInstalledCheckvs.AppItem).
- Fixed typo for the
-
Comments in Security Definition:
- Corrected an error in the comments describing how to authenticate requests, including correct HTTP methods (
GETinstead ofPOST).
- Corrected an error in the comments describing how to authenticate requests, including correct HTTP methods (
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.
| @@ -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] | |||
There was a problem hiding this comment.
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/backup/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.
| @@ -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: <current_unix_timestamp>" | |||
| // @description ``` | |||
There was a problem hiding this comment.
The change in command line URL from "/api/v1/resource" to "/api/v1/dashboard/current" seems incorrect. The API endpoint should remain consistent with intended functionality based on the original description provided. Additionally, there's no explanation or documentation about the purpose of including "dashboard" in the URL, which could confuse users.
|
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: wanghe-fit2cloud The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
No description provided.