From 3118c639f67cb591fc401c101a5696bb8d7eb181 Mon Sep 17 00:00:00 2001 From: Matt Hook Date: Tue, 4 Apr 2023 16:59:26 +1200 Subject: [PATCH] fix(docs): add missing swagger docs for upload file [EE-4886] (#8707) * add docs for uploading files via host management features * fix other doc issues --- api/http/handler/edgejobs/edgejob_delete.go | 2 +- api/http/handler/edgejobs/edgejob_file.go | 2 +- api/http/handler/edgejobs/edgejob_inspect.go | 2 +- .../edgejobs/edgejob_tasklogs_clear.go | 4 +-- .../edgejobs/edgejob_tasklogs_collect.go | 4 +-- .../edgejobs/edgejob_tasklogs_inspect.go | 4 +-- .../handler/edgejobs/edgejob_tasks_list.go | 2 +- api/http/handler/edgejobs/edgejob_update.go | 2 +- .../handler/edgestacks/edgestack_delete.go | 2 +- api/http/handler/edgestacks/edgestack_file.go | 2 +- .../handler/edgestacks/edgestack_inspect.go | 2 +- .../edgestacks/edgestack_status_delete.go | 2 +- .../edgestacks/edgestack_status_update.go | 2 +- .../handler/edgestacks/edgestack_update.go | 2 +- .../endpointedge/endpoint_edgejob_logs.go | 4 +-- .../endpoint_edgestack_inspect.go | 4 +-- .../endpoints/endpoint_agent_browse_docs.go | 25 ++++++++++++++++++ api/http/handler/handler.go | 26 +++++++++---------- api/http/handler/helm/helm_delete.go | 2 +- api/http/handler/helm/helm_list.go | 6 ++--- api/http/handler/teams/team_delete.go | 2 +- api/http/handler/teams/team_memberships.go | 2 +- package.json | 2 +- 23 files changed, 66 insertions(+), 41 deletions(-) create mode 100644 api/http/handler/endpoints/endpoint_agent_browse_docs.go diff --git a/api/http/handler/edgejobs/edgejob_delete.go b/api/http/handler/edgejobs/edgejob_delete.go index 383951cf1..471d374dc 100644 --- a/api/http/handler/edgejobs/edgejob_delete.go +++ b/api/http/handler/edgejobs/edgejob_delete.go @@ -19,7 +19,7 @@ import ( // @tags edge_jobs // @security ApiKeyAuth // @security jwt -// @param id path string true "EdgeJob Id" +// @param id path int true "EdgeJob Id" // @success 204 // @failure 500 // @failure 400 diff --git a/api/http/handler/edgejobs/edgejob_file.go b/api/http/handler/edgejobs/edgejob_file.go index 0af631e5a..0c06586e5 100644 --- a/api/http/handler/edgejobs/edgejob_file.go +++ b/api/http/handler/edgejobs/edgejob_file.go @@ -20,7 +20,7 @@ type edgeJobFileResponse struct { // @security ApiKeyAuth // @security jwt // @produce json -// @param id path string true "EdgeJob Id" +// @param id path int true "EdgeJob Id" // @success 200 {object} edgeJobFileResponse // @failure 500 // @failure 400 diff --git a/api/http/handler/edgejobs/edgejob_inspect.go b/api/http/handler/edgejobs/edgejob_inspect.go index f90e87a8f..643608d15 100644 --- a/api/http/handler/edgejobs/edgejob_inspect.go +++ b/api/http/handler/edgejobs/edgejob_inspect.go @@ -21,7 +21,7 @@ type edgeJobInspectResponse struct { // @security ApiKeyAuth // @security jwt // @produce json -// @param id path string true "EdgeJob Id" +// @param id path int true "EdgeJob Id" // @success 200 {object} portainer.EdgeJob // @failure 500 // @failure 400 diff --git a/api/http/handler/edgejobs/edgejob_tasklogs_clear.go b/api/http/handler/edgejobs/edgejob_tasklogs_clear.go index 6fa1d18e9..109907f27 100644 --- a/api/http/handler/edgejobs/edgejob_tasklogs_clear.go +++ b/api/http/handler/edgejobs/edgejob_tasklogs_clear.go @@ -19,8 +19,8 @@ import ( // @security ApiKeyAuth // @security jwt // @produce json -// @param id path string true "EdgeJob Id" -// @param taskID path string true "Task Id" +// @param id path int true "EdgeJob Id" +// @param taskID path int true "Task Id" // @success 204 // @failure 500 // @failure 400 diff --git a/api/http/handler/edgejobs/edgejob_tasklogs_collect.go b/api/http/handler/edgejobs/edgejob_tasklogs_collect.go index bf89c747f..f6045ec0e 100644 --- a/api/http/handler/edgejobs/edgejob_tasklogs_collect.go +++ b/api/http/handler/edgejobs/edgejob_tasklogs_collect.go @@ -19,8 +19,8 @@ import ( // @security ApiKeyAuth // @security jwt // @produce json -// @param id path string true "EdgeJob Id" -// @param taskID path string true "Task Id" +// @param id path int true "EdgeJob Id" +// @param taskID path int true "Task Id" // @success 204 // @failure 500 // @failure 400 diff --git a/api/http/handler/edgejobs/edgejob_tasklogs_inspect.go b/api/http/handler/edgejobs/edgejob_tasklogs_inspect.go index 68da525e1..4f45f39c2 100644 --- a/api/http/handler/edgejobs/edgejob_tasklogs_inspect.go +++ b/api/http/handler/edgejobs/edgejob_tasklogs_inspect.go @@ -20,8 +20,8 @@ type fileResponse struct { // @security ApiKeyAuth // @security jwt // @produce json -// @param id path string true "EdgeJob Id" -// @param taskID path string true "Task Id" +// @param id path int true "EdgeJob Id" +// @param taskID path int true "Task Id" // @success 200 {object} fileResponse // @failure 500 // @failure 400 diff --git a/api/http/handler/edgejobs/edgejob_tasks_list.go b/api/http/handler/edgejobs/edgejob_tasks_list.go index 095c8898d..8d30716b3 100644 --- a/api/http/handler/edgejobs/edgejob_tasks_list.go +++ b/api/http/handler/edgejobs/edgejob_tasks_list.go @@ -25,7 +25,7 @@ type taskContainer struct { // @security ApiKeyAuth // @security jwt // @produce json -// @param id path string true "EdgeJob Id" +// @param id path int true "EdgeJob Id" // @success 200 {array} taskContainer // @failure 500 // @failure 400 diff --git a/api/http/handler/edgejobs/edgejob_update.go b/api/http/handler/edgejobs/edgejob_update.go index 00d3bdae9..99a95d499 100644 --- a/api/http/handler/edgejobs/edgejob_update.go +++ b/api/http/handler/edgejobs/edgejob_update.go @@ -41,7 +41,7 @@ func (payload *edgeJobUpdatePayload) Validate(r *http.Request) error { // @security jwt // @accept json // @produce json -// @param id path string true "EdgeJob Id" +// @param id path int true "EdgeJob Id" // @param body body edgeJobUpdatePayload true "EdgeGroup data" // @success 200 {object} portainer.EdgeJob // @failure 500 diff --git a/api/http/handler/edgestacks/edgestack_delete.go b/api/http/handler/edgestacks/edgestack_delete.go index 2ae611e2e..edbd602a8 100644 --- a/api/http/handler/edgestacks/edgestack_delete.go +++ b/api/http/handler/edgestacks/edgestack_delete.go @@ -15,7 +15,7 @@ import ( // @tags edge_stacks // @security ApiKeyAuth // @security jwt -// @param id path string true "EdgeStack Id" +// @param id path int true "EdgeStack Id" // @success 204 // @failure 500 // @failure 400 diff --git a/api/http/handler/edgestacks/edgestack_file.go b/api/http/handler/edgestacks/edgestack_file.go index ee5f96f08..5640020db 100644 --- a/api/http/handler/edgestacks/edgestack_file.go +++ b/api/http/handler/edgestacks/edgestack_file.go @@ -20,7 +20,7 @@ type stackFileResponse struct { // @security ApiKeyAuth // @security jwt // @produce json -// @param id path string true "EdgeStack Id" +// @param id path int true "EdgeStack Id" // @success 200 {object} stackFileResponse // @failure 500 // @failure 400 diff --git a/api/http/handler/edgestacks/edgestack_inspect.go b/api/http/handler/edgestacks/edgestack_inspect.go index 2be90a3a7..5ca058cb4 100644 --- a/api/http/handler/edgestacks/edgestack_inspect.go +++ b/api/http/handler/edgestacks/edgestack_inspect.go @@ -16,7 +16,7 @@ import ( // @security ApiKeyAuth // @security jwt // @produce json -// @param id path string true "EdgeStack Id" +// @param id path int true "EdgeStack Id" // @success 200 {object} portainer.EdgeStack // @failure 500 // @failure 400 diff --git a/api/http/handler/edgestacks/edgestack_status_delete.go b/api/http/handler/edgestacks/edgestack_status_delete.go index 1ffdabe83..a5bd29052 100644 --- a/api/http/handler/edgestacks/edgestack_status_delete.go +++ b/api/http/handler/edgestacks/edgestack_status_delete.go @@ -15,7 +15,7 @@ import ( // @description Authorized only if the request is done by an Edge Environment(Endpoint) // @tags edge_stacks // @produce json -// @param id path string true "EdgeStack Id" +// @param id path int true "EdgeStack Id" // @success 200 {object} portainer.EdgeStack // @failure 500 // @failure 400 diff --git a/api/http/handler/edgestacks/edgestack_status_update.go b/api/http/handler/edgestacks/edgestack_status_update.go index fc2aea0dc..a6a194c02 100644 --- a/api/http/handler/edgestacks/edgestack_status_update.go +++ b/api/http/handler/edgestacks/edgestack_status_update.go @@ -40,7 +40,7 @@ func (payload *updateStatusPayload) Validate(r *http.Request) error { // @tags edge_stacks // @accept json // @produce json -// @param id path string true "EdgeStack Id" +// @param id path int true "EdgeStack Id" // @success 200 {object} portainer.EdgeStack // @failure 500 // @failure 400 diff --git a/api/http/handler/edgestacks/edgestack_update.go b/api/http/handler/edgestacks/edgestack_update.go index 83b93f6fe..c167d7661 100644 --- a/api/http/handler/edgestacks/edgestack_update.go +++ b/api/http/handler/edgestacks/edgestack_update.go @@ -42,7 +42,7 @@ func (payload *updateEdgeStackPayload) Validate(r *http.Request) error { // @security jwt // @accept json // @produce json -// @param id path string true "EdgeStack Id" +// @param id path int true "EdgeStack Id" // @param body body updateEdgeStackPayload true "EdgeStack data" // @success 200 {object} portainer.EdgeStack // @failure 500 diff --git a/api/http/handler/endpointedge/endpoint_edgejob_logs.go b/api/http/handler/endpointedge/endpoint_edgejob_logs.go index a06c11fed..e752443d4 100644 --- a/api/http/handler/endpointedge/endpoint_edgejob_logs.go +++ b/api/http/handler/endpointedge/endpoint_edgejob_logs.go @@ -25,8 +25,8 @@ func (payload *logsPayload) Validate(r *http.Request) error { // @tags edge, endpoints // @accept json // @produce json -// @param id path string true "environment(endpoint) Id" -// @param jobID path string true "Job Id" +// @param id path int true "environment(endpoint) Id" +// @param jobID path int true "Job Id" // @success 200 // @failure 500 // @failure 400 diff --git a/api/http/handler/endpointedge/endpoint_edgestack_inspect.go b/api/http/handler/endpointedge/endpoint_edgestack_inspect.go index ed874c0fc..00b4dfccc 100644 --- a/api/http/handler/endpointedge/endpoint_edgestack_inspect.go +++ b/api/http/handler/endpointedge/endpoint_edgestack_inspect.go @@ -25,8 +25,8 @@ type configResponse struct { // @tags edge, endpoints, edge_stacks // @accept json // @produce json -// @param id path string true "environment(endpoint) Id" -// @param stackId path string true "EdgeStack Id" +// @param id path int true "environment(endpoint) Id" +// @param stackId path int true "EdgeStack Id" // @success 200 {object} configResponse // @failure 500 // @failure 400 diff --git a/api/http/handler/endpoints/endpoint_agent_browse_docs.go b/api/http/handler/endpoints/endpoint_agent_browse_docs.go new file mode 100644 index 000000000..c8d642644 --- /dev/null +++ b/api/http/handler/endpoints/endpoint_agent_browse_docs.go @@ -0,0 +1,25 @@ +package endpoints + +/// This feature is implemented in the agent API and not directly here. +/// However, it's proxied. So we document it here. + +// @summary Upload a file under a specific path on the file system of an environment (endpoint) +// @description Use this environment(endpoint) to upload TLS files. +// @description **Access policy**: administrator +// @tags endpoints +// @security ApiKeyAuth +// @security jwt +// @accept multipart/form-data +// @produce json +// @param id path int true "Environment(Endpoint) identifier" +// @param volumeID query string false "Optional volume identifier to upload the file" +// @param Path formData string true "The destination path to upload the file to" +// @param file formData file true "The file to upload" +// @success 204 "Success" +// @failure 400 "Invalid request" +// @failure 500 "Server error" +// @router /endpoints/{id}/docker/v2/browse/put [post] +func _fileBrowseFileUploadV2() { + // dummy function to make swag pick up the above docs for the following REST call + // POST request on /browse/put?volumeID=:id +} diff --git a/api/http/handler/handler.go b/api/http/handler/handler.go index e79b7b9e9..a14a0bb13 100644 --- a/api/http/handler/handler.go +++ b/api/http/handler/handler.go @@ -97,7 +97,7 @@ type Handler struct { // @securitydefinitions.apikey ApiKeyAuth // @in header -// @name Authorization +// @name x-api-key // @securitydefinitions.apikey jwt // @in header @@ -107,6 +107,8 @@ type Handler struct { // @tag.description Authenticate against Portainer HTTP API // @tag.name custom_templates // @tag.description Manage Custom Templates +// @tag.name edge +// @tag.description Manage Edge related environment(endpoint) settings // @tag.name edge_groups // @tag.description Manage Edge Groups // @tag.name edge_jobs @@ -115,8 +117,6 @@ type Handler struct { // @tag.description Manage Edge Stacks // @tag.name edge_templates // @tag.description Manage Edge Templates -// @tag.name edge -// @tag.description Manage Edge related environment(endpoint) settings // @tag.name endpoints // @tag.description Manage Docker environments(endpoints) // @tag.name endpoint_groups @@ -133,8 +133,14 @@ type Handler struct { // @tag.description Manage roles // @tag.name settings // @tag.description Manage Portainer settings -// @tag.name users -// @tag.description Manage users +// @tag.name ssl +// @tag.description Manage ssl settings +// @tag.name stacks +// @tag.description Manage stacks +// @tag.name status +// @tag.description Information about the Portainer instance +// @tag.name system +// @tag.description Manage Portainer system // @tag.name tags // @tag.description Manage tags // @tag.name teams @@ -143,20 +149,14 @@ type Handler struct { // @tag.description Manage team memberships // @tag.name templates // @tag.description Manage App Templates -// @tag.name stacks -// @tag.description Manage stacks -// @tag.name ssl -// @tag.description Manage ssl settings +// @tag.name users +// @tag.description Manage users // @tag.name upload // @tag.description Upload files // @tag.name webhooks // @tag.description Manage webhooks // @tag.name websocket // @tag.description Create exec sessions using websockets -// @tag.name status -// @tag.description Information about the Portainer instance -// @tag.name system -// @tag.description Manage Portainer system // ServeHTTP delegates a request to the appropriate subhandler. func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) { diff --git a/api/http/handler/helm/helm_delete.go b/api/http/handler/helm/helm_delete.go index 5803ce26f..d92e7f63c 100644 --- a/api/http/handler/helm/helm_delete.go +++ b/api/http/handler/helm/helm_delete.go @@ -18,7 +18,7 @@ import ( // @security jwt // @param id path int true "Environment(Endpoint) identifier" // @param release path string true "The name of the release/application to uninstall" -// @param namespace query string true "An optional namespace" +// @param namespace query string false "An optional namespace" // @success 204 "Success" // @failure 400 "Invalid environment(endpoint) id or bad request" // @failure 401 "Unauthorized" diff --git a/api/http/handler/helm/helm_list.go b/api/http/handler/helm/helm_list.go index 3aab6c264..12565c4f0 100644 --- a/api/http/handler/helm/helm_list.go +++ b/api/http/handler/helm/helm_list.go @@ -20,9 +20,9 @@ import ( // @accept json // @produce json // @param id path int true "Environment(Endpoint) identifier" -// @param namespace query string true "specify an optional namespace" -// @param filter query string true "specify an optional filter" -// @param selector query string true "specify an optional selector" +// @param namespace query string false "specify an optional namespace" +// @param filter query string false "specify an optional filter" +// @param selector query string false "specify an optional selector" // @success 200 {array} release.ReleaseElement "Success" // @failure 400 "Invalid environment(endpoint) identifier" // @failure 401 "Unauthorized" diff --git a/api/http/handler/teams/team_delete.go b/api/http/handler/teams/team_delete.go index e67f427c2..294d69ae4 100644 --- a/api/http/handler/teams/team_delete.go +++ b/api/http/handler/teams/team_delete.go @@ -17,7 +17,7 @@ import ( // @tags teams // @security ApiKeyAuth // @security jwt -// @param id path string true "Team Id" +// @param id path int true "Team Id" // @success 204 "Success" // @failure 400 "Invalid request" // @failure 403 "Permission denied" diff --git a/api/http/handler/teams/team_memberships.go b/api/http/handler/teams/team_memberships.go index ada0bc150..aeeded983 100644 --- a/api/http/handler/teams/team_memberships.go +++ b/api/http/handler/teams/team_memberships.go @@ -19,7 +19,7 @@ import ( // @security ApiKeyAuth // @security jwt // @produce json -// @param id path string true "Team Id" +// @param id path int true "Team Id" // @success 200 {array} portainer.TeamMembership "Success" // @failure 400 "Invalid request" // @failure 403 "Permission denied" diff --git a/package.json b/package.json index d38131e50..aafc35d3e 100644 --- a/package.json +++ b/package.json @@ -20,7 +20,7 @@ "build": "grunt clean:all && grunt build", "build:server": "grunt clean:server && grunt build:server", "build:client": "grunt clean:client && grunt build:client", - "prebuild:docs": "go install github.com/swaggo/swag/cmd/swag@v1.7.1", + "prebuild:docs": "go install github.com/swaggo/swag/cmd/swag@v1.8.11", "build:docs": "cd api && swag init -g ./http/handler/handler.go --parseDependency --parseInternal --parseDepth 2 --markdownFiles ./", "validate:docs": "swagger2openapi --warnOnly api/docs/swagger.yaml -o api/docs/openapi.yaml && swagger-cli validate api/docs/openapi.yaml", "clean": "grunt clean:all",