fix(docs): add missing swagger docs for upload file [EE-4886] (#8708)

* add docs for uploading files via host management features

* fix other doc issues

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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
+}

api/http/handler/handler.go

@@ -99,7 +99,7 @@ type Handler struct {
 
 // @securitydefinitions.apikey ApiKeyAuth
 // @in header
-// @name Authorization
+// @name x-api-key
 
 // @securitydefinitions.apikey jwt
 // @in header
@@ -109,6 +109,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
@@ -117,8 +119,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
@@ -137,8 +137,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
@@ -147,20 +153,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) {

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"

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"

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"

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"

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",