fix(swagger) Fix openapi issues (#5123)

* * fix api version
* fix license info
* fix error response schema
* fix other typos & mistakes

* * remove unused tag

* * fix helm issues

api/http/handler/customtemplates/customtemplate_create.go

@@ -21,7 +21,7 @@ import (
 // @description **Access policy**: authenticated
 // @tags custom_templates
 // @security jwt
-// @accept json, multipart/form-data
+// @accept json,multipart/form-data
 // @produce json
 // @param method query string true "method for creating template" Enums(string, file, repository)
 // @param body_string body customTemplateFromFileContentPayload false "Required when using method=string"

api/http/handler/edgegroups/edgegroup_create.go

@@ -41,7 +41,7 @@ func (payload *edgeGroupCreatePayload) Validate(r *http.Request) error {
 // @produce json
 // @param body body edgeGroupCreatePayload true "EdgeGroup data"
 // @success 200 {object} portainer.EdgeGroup
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @failure 500
 // @router /edge_groups [post]
 func (handler *Handler) edgeGroupCreate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {

api/http/handler/edgegroups/edgegroup_delete.go

@@ -20,7 +20,7 @@ import (
 // @produce json
 // @param id path int true "EdgeGroup Id"
 // @success 204
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @failure 500
 // @router /edge_groups/{id} [delete]
 func (handler *Handler) edgeGroupDelete(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {

api/http/handler/edgegroups/edgegroup_inspect.go

@@ -19,7 +19,7 @@ import (
 // @produce json
 // @param id path int true "EdgeGroup Id"
 // @success 200 {object} portainer.EdgeGroup
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @failure 500
 // @router /edge_groups/{id} [get]
 func (handler *Handler) edgeGroupInspect(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {

api/http/handler/edgegroups/edgegroup_list.go

@@ -24,7 +24,7 @@ type decoratedEdgeGroup struct {
 // @produce json
 // @success 200 {array} portainer.EdgeGroup{HasEdgeStack=bool} "EdgeGroups"
 // @failure 500
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_groups [get]
 func (handler *Handler) edgeGroupList(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeGroups, err := handler.DataStore.EdgeGroup().EdgeGroups()

api/http/handler/edgegroups/edgegroup_update.go

@@ -44,7 +44,7 @@ func (payload *edgeGroupUpdatePayload) Validate(r *http.Request) error {
 // @param id path int true "EdgeGroup Id"
 // @param body body edgeGroupUpdatePayload true "EdgeGroup data"
 // @success 200 {object} portainer.EdgeGroup
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @failure 500
 // @router /edge_groups/{id} [put]
 func (handler *Handler) edgeGroupUpdate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {

api/http/handler/edgejobs/edgejob_create.go

@@ -22,10 +22,10 @@ import (
 // @accept json
 // @produce json
 // @param method query string true "Creation Method" Enums(file, string)
-// @param body body edgeJobCreateFromFileContentPayload true "EdgeGroup data when method is string"
-// @param body body edgeJobCreateFromFilePayload true "EdgeGroup data when method is file"
+// @param body_string body edgeJobCreateFromFileContentPayload true "EdgeGroup data when method is string"
+// @param body_file body edgeJobCreateFromFilePayload true "EdgeGroup data when method is file"
 // @success 200 {object} portainer.EdgeGroup
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @failure 500
 // @router /edge_jobs [post]
 func (handler *Handler) edgeJobCreate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {

api/http/handler/edgejobs/edgejob_delete.go

@@ -22,7 +22,7 @@ import (
 // @success 204
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_jobs/{id} [delete]
 func (handler *Handler) edgeJobDelete(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeJobID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgejobs/edgejob_file.go

@@ -25,7 +25,7 @@ type edgeJobFileResponse struct {
 // @success 200 {object} edgeJobFileResponse
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_jobs/{id}/file [get]
 func (handler *Handler) edgeJobFile(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeJobID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgejobs/edgejob_inspect.go

@@ -26,7 +26,7 @@ type edgeJobInspectResponse struct {
 // @success 200 {object} portainer.EdgeJob
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_jobs/{id} [get]
 func (handler *Handler) edgeJobInspect(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeJobID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgejobs/edgejob_list.go

@@ -17,7 +17,7 @@ import (
 // @success 200 {array} portainer.EdgeJob
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_jobs [get]
 // GET request on /api/edge_jobs
 func (handler *Handler) edgeJobList(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {

api/http/handler/edgejobs/edgejob_tasklogs_clear.go

@@ -23,7 +23,7 @@ import (
 // @success 204
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_jobs/{id}/tasks/{taskID}/logs [delete]
 func (handler *Handler) edgeJobTasksClear(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeJobID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgejobs/edgejob_tasklogs_collect.go

@@ -22,7 +22,7 @@ import (
 // @success 204
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_jobs/{id}/tasks/{taskID}/logs [post]
 func (handler *Handler) edgeJobTasksCollect(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeJobID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgejobs/edgejob_tasklogs_inspect.go

@@ -25,7 +25,7 @@ type fileResponse struct {
 // @success 200 {object} fileResponse
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_jobs/{id}/tasks/{taskID}/logs [get]
 func (handler *Handler) edgeJobTaskLogsInspect(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeJobID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgejobs/edgejob_tasks_list.go

@@ -28,7 +28,7 @@ type taskContainer struct {
 // @success 200 {array} taskContainer
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_jobs/{id}/tasks [get]
 func (handler *Handler) edgeJobTasksList(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeJobID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgejobs/edgejob_update.go

@@ -40,7 +40,7 @@ func (payload *edgeJobUpdatePayload) Validate(r *http.Request) error {
 // @success 200 {object} portainer.EdgeJob
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_jobs/{id} [post]
 func (handler *Handler) edgeJobUpdate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeJobID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgestacks/edgestack_create.go

@@ -30,7 +30,7 @@ import (
 // @param body_repository body swarmStackFromGitRepositoryPayload true "Required when using method=repository"
 // @success 200 {object} portainer.EdgeStack
 // @failure 500
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_stacks [post]
 func (handler *Handler) edgeStackCreate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	method, err := request.RetrieveQueryParameter(r, "method", false)

api/http/handler/edgestacks/edgestack_delete.go

@@ -22,7 +22,7 @@ import (
 // @success 204
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_stacks/{id} [delete]
 func (handler *Handler) edgeStackDelete(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeStackID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgestacks/edgestack_file.go

@@ -26,7 +26,7 @@ type stackFileResponse struct {
 // @success 200 {object} stackFileResponse
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_stacks/{id}/file [get]
 func (handler *Handler) edgeStackFile(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgestacks/edgestack_inspect.go

@@ -21,7 +21,7 @@ import (
 // @success 200 {object} portainer.EdgeStack
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_stacks/{id} [get]
 func (handler *Handler) edgeStackInspect(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeStackID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/edgestacks/edgestack_list.go

@@ -17,7 +17,7 @@ import (
 // @success 200 {array} portainer.EdgeStack
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_stacks [get]
 func (handler *Handler) edgeStackList(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeStacks, err := handler.DataStore.EdgeStack().EdgeStacks()

api/http/handler/edgestacks/edgestack_update.go

@@ -43,7 +43,7 @@ func (payload *updateEdgeStackPayload) Validate(r *http.Request) error {
 // @success 200 {object} portainer.EdgeStack
 // @failure 500
 // @failure 400
-// @failure 503 Edge compute features are disabled
+// @failure 503 "Edge compute features are disabled"
 // @router /edge_stacks/{id} [put]
 func (handler *Handler) edgeStackUpdate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")

api/http/handler/endpointedge/endpoint_edgestack_inspect.go

@@ -24,7 +24,7 @@ type configResponse struct {
 // @accept json
 // @produce json
 // @param id path string true "Endpoint Id"
-// @param stackID path string true "EdgeStack Id"
+// @param stackId path string true "EdgeStack Id"
 // @success 200 {object} configResponse
 // @failure 500
 // @failure 400

api/http/handler/endpointgroups/endpointgroup_inspect.go

@@ -22,7 +22,7 @@ import (
 // @failure 400 "Invalid request"
 // @failure 404 "EndpointGroup not found"
 // @failure 500 "Server error"
-// @router /endpoint_groups/:id [get]
+// @router /endpoint_groups/{id} [get]
 func (handler *Handler) endpointGroupInspect(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointGroupID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {

api/http/handler/endpointgroups/endpointgroup_update.go

@@ -41,7 +41,7 @@ func (payload *endpointGroupUpdatePayload) Validate(r *http.Request) error {
 // @failure 400 "Invalid request"
 // @failure 404 "EndpointGroup not found"
 // @failure 500 "Server error"
-// @router /endpoint_groups/:id [put]
+// @router /endpoint_groups/{id} [put]
 func (handler *Handler) endpointGroupUpdate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointGroupID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {

api/http/handler/endpoints/endpoint_association_delete.go

@@ -4,14 +4,15 @@ import (
 	"encoding/base64"
 	"errors"
 	"fmt"
+	"net/http"
+	"regexp"
+	"strings"
+
 	httperror "github.com/portainer/libhttp/error"
 	"github.com/portainer/libhttp/request"
 	"github.com/portainer/libhttp/response"
 	portainer "github.com/portainer/portainer/api"
 	bolterrors "github.com/portainer/portainer/api/bolt/errors"
-	"net/http"
-	"regexp"
-	"strings"
 )
 
 // @id EndpointAssociationDelete
@@ -26,7 +27,7 @@ import (
 // @failure 400 "Invalid request"
 // @failure 404 "Endpoint not found"
 // @failure 500 "Server error"
-// @router /api/endpoints/:id/association [put]
+// @router /api/endpoints/{id}/association [put]
 func (handler *Handler) endpointAssociationDelete(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {
@@ -84,5 +85,5 @@ func (handler *Handler) updateEdgeKey(edgeKey string) (string, error) {
 
 func getPort(url string) string {
 	items := strings.Split(url, ":")
-	return items[len(items) - 1]
+	return items[len(items)-1]
 }

api/http/handler/endpoints/endpoint_list.go

@@ -31,7 +31,7 @@ import (
 // @param tagsPartialMatch query bool false "If true, will return endpoint which has one of tagIds, if false (or missing) will return only endpoints that has all the tags"
 // @param endpointIds query []int false "will return only these endpoints"
 // @success 200 {array} portainer.Endpoint "Endpoints"
-// @failure 500 Server error
+// @failure 500 "Server error"
 // @router /endpoints [get]
 func (handler *Handler) endpointList(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	start, _ := request.RetrieveNumericQueryParameter(r, "start", true)

api/http/handler/endpoints/endpoint_settings_update.go

@@ -49,7 +49,7 @@ func (payload *endpointSettingsUpdatePayload) Validate(r *http.Request) error {
 // @failure 400 "Invalid request"
 // @failure 404 "Endpoint not found"
 // @failure 500 "Server error"
-// @router /api/endpoints/:id/settings [put]
+// @router /api/endpoints/{id}/settings [put]
 func (handler *Handler) endpointSettingsUpdate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {

api/http/handler/handler.go

@@ -78,8 +78,8 @@ type Handler struct {
 
 // @contact.email info@portainer.io
 
-// @license.name
-// @license.url
+// @license.name zlib
+// @license.url https://github.com/portainer/portainer/blob/develop/LICENSE
 
 // @host
 // @BasePath /api
@@ -121,8 +121,6 @@ type Handler struct {
 // @tag.description Manage Portainer settings
 // @tag.name status
 // @tag.description Information about the Portainer instance
-// @tag.name stacks
-// @tag.description Manage Docker stacks
 // @tag.name users
 // @tag.description Manage users
 // @tag.name tags

api/http/handler/helm/helm_delete.go

@@ -17,14 +17,15 @@ import (
 // @security jwt
 // @accept json
 // @produce json
-// @param release query string true "The name of the release/application to uninstall"
+// @param id path int true "Endpoint identifier"
+// @param release path string true "The name of the release/application to uninstall"
 // @param namespace query string true "An optional namespace"
 // @success 204 "Success"
 // @failure 400 "Invalid endpoint id or bad request"
 // @failure 401 "Unauthorized"
 // @failure 404 "Endpoint or ServiceAccount not found"
 // @failure 500 "Server error or helm error"
-// @router /endpoints/:id/kubernetes/helm/{release} [delete]
+// @router /endpoints/{id}/kubernetes/helm/{release} [delete]
 func (handler *Handler) helmDelete(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	release, err := request.RetrieveRouteVariableValue(r, "release")
 	if err != nil {

api/http/handler/helm/helm_install.go

@@ -36,12 +36,13 @@ var errChartNameInvalid = errors.New("invalid chart name. " +
 // @security jwt
 // @accept json
 // @produce json
+// @param id path int true "Endpoint identifier"
 // @param payload body installChartPayload true "Chart details"
 // @success 201 {object} release.Release "Created"
 // @failure 401 "Unauthorized"
 // @failure 404 "Endpoint or ServiceAccount not found"
 // @failure 500 "Server error"
-// @router /endpoints/:id/kubernetes/helm [post]
+// @router /endpoints/{id}/kubernetes/helm [post]
 func (handler *Handler) helmInstall(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	var payload installChartPayload
 	err := request.DecodeAndValidateJSONPayload(r, &payload)

api/http/handler/helm/helm_list.go

@@ -17,6 +17,7 @@ import (
 // @security jwt
 // @accept json
 // @produce json
+// @param id path int true "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"
@@ -25,7 +26,7 @@ import (
 // @failure 401 "Unauthorized"
 // @failure 404 "Endpoint or ServiceAccount not found"
 // @failure 500 "Server error"
-// @router /endpoints/:id/kubernetes/helm [get]
+// @router /endpoints/{id}/kubernetes/helm [get]
 func (handler *Handler) helmList(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	clusterAccess, httperr := handler.getHelmClusterAccess(r)
 	if httperr != nil {

api/http/handler/helm/helm_show.go

@@ -19,7 +19,7 @@ import (
 // @tags helm_chart
 // @param repo query string true "Helm repository URL"
 // @param chart query string true "Chart name"
-// @param command path string false "chart/values/readme"
+// @param command path string true "chart/values/readme"
 // @security jwt
 // @accept json
 // @produce text/plain

api/http/handler/helm/user_helm_repos.go

@@ -36,12 +36,13 @@ func (p *addHelmRepoUrlPayload) Validate(_ *http.Request) error {
 // @security jwt
 // @accept json
 // @produce json
+// @param id path int true "Endpoint identifier"
 // @param payload body addHelmRepoUrlPayload true "Helm Repository"
 // @success 200 {object} portainer.HelmUserRepository "Success"
 // @failure 400 "Invalid request"
 // @failure 403 "Permission denied"
 // @failure 500 "Server error"
-// @router /endpoints/:id/kubernetes/helm/repositories [post]
+// @router /endpoints/{id}/kubernetes/helm/repositories [post]
 func (handler *Handler) userCreateHelmRepo(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	tokenData, err := security.RetrieveTokenData(r)
 	if err != nil {
@@ -99,7 +100,7 @@ func (handler *Handler) userCreateHelmRepo(w http.ResponseWriter, r *http.Reques
 // @failure 400 "Invalid request"
 // @failure 403 "Permission denied"
 // @failure 500 "Server error"
-// @router /endpoints/:id/kubernetes/helm/repositories [get]
+// @router /endpoints/{id}/kubernetes/helm/repositories [get]
 func (handler *Handler) userGetHelmRepos(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	tokenData, err := security.RetrieveTokenData(r)
 	if err != nil {

api/http/handler/stacks/stack_create.go

@@ -36,7 +36,7 @@ func (handler *Handler) cleanUp(stack *portainer.Stack, doCleanUp *bool) error {
 // @description **Access policy**: restricted
 // @tags stacks
 // @security jwt
-// @accept json, multipart/form-data
+// @accept json,multipart/form-data
 // @produce json
 // @param type query int true "Stack deployment type. Possible values: 1 (Swarm stack) or 2 (Compose stack)." Enums(1,2)
 // @param method query string true "Stack deployment method. Possible values: file, string or repository." Enums(string, file, repository)

api/http/handler/stacks/stack_update_git_redeploy.go

@@ -53,7 +53,7 @@ func (payload *stackGitRedployPayload) Validate(r *http.Request) error {
 // @failure 403 "Permission denied"
 // @failure 404 "Not found"
 // @failure 500 "Server error"
-// @router /stacks/:id/git/redeploy [put]
+// @router /stacks/{id}/git/redeploy [put]
 func (handler *Handler) stackGitRedeploy(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {

api/http/handler/teams/team_delete.go

@@ -17,6 +17,7 @@ import (
 // @description **Access policy**: administrator
 // @tags teams
 // @security jwt
+// @param id path string true "Team Id"
 // @success 204 "Success"
 // @failure 400 "Invalid request"
 // @failure 403 "Permission denied"

api/http/handler/teams/team_memberships.go

@@ -18,6 +18,7 @@ import (
 // @tags team_memberships
 // @security jwt
 // @produce json
+// @param id path string true "Team Id"
 // @success 200 {array} portainer.TeamMembership "Success"
 // @failure 400 "Invalid request"
 // @failure 403 "Permission denied"