fix(swagger) swagger annotations fixes and improvements EE-1205

api/http/handler/stacks/stack_associate.go

@@ -14,7 +14,22 @@ import (
 	"github.com/portainer/portainer/api/internal/stackutils"
 )
 
-// PUT request on /api/stacks/:id/associate?endpointId=<endpointId>&swarmId=<swarmId>&orphanedRunning=<orphanedRunning>
+// @id StackAssociate
+// @summary Associate an orphaned stack to a new environment(endpoint)
+// @description **Access policy**: administrator
+// @tags stacks
+// @security jwt
+// @produce json
+// @param id path int true "Stack identifier"
+// @param endpointId query int true "Stacks created before version 1.18.0 might not have an associated environment(endpoint) identifier. Use this optional parameter to set the environment(endpoint) identifier used by the stack."
+// @param swarmId query int true "Swarm identifier"
+// @param orphanedRunning query boolean true "Indicates whether the stack is orphaned"
+// @success 200 {object} portainer.Stack "Success"
+// @failure 400 "Invalid request"
+// @failure 403 "Permission denied"
+// @failure 404 "Stack not found"
+// @failure 500 "Server error"
+// @router /stacks/{id}/associate [put]
 func (handler *Handler) stackAssociate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {

api/http/handler/stacks/stack_create.go

@@ -33,7 +33,7 @@ func (handler *Handler) cleanUp(stack *portainer.Stack, doCleanUp *bool) error {
 // @id StackCreate
 // @summary Deploy a new stack
 // @description Deploy a new stack into a Docker environment(endpoint) specified via the environment(endpoint) identifier.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @accept json,multipart/form-data

api/http/handler/stacks/stack_list.go

@@ -24,7 +24,7 @@ type stackListOperationFilters struct {
 // @description List all stacks based on the current user authorizations.
 // @description Will return all stacks if using an administrator account otherwise it
 // @description will only return the list of stacks the user have access to.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @param filters query string false "Filters to process on the stack list. Encoded as JSON (a map[string]string). For example, {"SwarmID": "jpofkc0i9uo9wtx1zesuk649w"} will only return stacks that are part of the specified Swarm cluster. Available filters: EndpointID, SwarmID."

api/http/handler/stacks/stack_migrate.go

@@ -34,7 +34,7 @@ func (payload *stackMigratePayload) Validate(r *http.Request) error {
 // @id StackMigrate
 // @summary Migrate a stack to another environment(endpoint)
 // @description  Migrate a stack from an environment(endpoint) to another environment(endpoint). It will re-create the stack inside the target environment(endpoint) before removing the original stack.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @produce json

api/http/handler/stacks/stack_start.go

@@ -20,7 +20,7 @@ import (
 // @id StackStart
 // @summary Starts a stopped Stack
 // @description Starts a stopped Stack.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @param id path int true "Stack identifier"

api/http/handler/stacks/stack_stop.go

@@ -18,7 +18,7 @@ import (
 // @id StackStop
 // @summary Stops a stopped Stack
 // @description Stops a stopped Stack.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @param id path int true "Stack identifier"

api/http/handler/stacks/stack_update.go

@@ -51,7 +51,7 @@ func (payload *updateSwarmStackPayload) Validate(r *http.Request) error {
 // @id StackUpdate
 // @summary Update a stack
 // @description Update a stack.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @accept json

api/http/handler/stacks/stack_update_git.go

@@ -40,7 +40,7 @@ func (payload *stackGitUpdatePayload) Validate(r *http.Request) error {
 // @id StackUpdateGit
 // @summary Update a stack's Git configs
 // @description Update the Git settings in a stack, e.g., RepositoryReferenceName and AutoUpdate
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @accept json

api/http/handler/stacks/stack_update_git_redeploy.go

@@ -38,7 +38,7 @@ func (payload *stackGitRedployPayload) Validate(r *http.Request) error {
 // @id StackGitRedeploy
 // @summary Redeploy a stack
 // @description Pull and redeploy a stack via Git
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @accept json

api/http/handler/stacks/webhook_invoke.go

@@ -15,6 +15,16 @@ import (
 	"github.com/portainer/libhttp/request"
 )
 
+// @id WebhookInvoke
+// @summary Webhook for triggering stack updates from git
+// @description **Access policy**: public
+// @tags stacks
+// @param webhookID path string true "Stack identifier"
+// @success 200 "Success"
+// @failure 400 "Invalid request"
+// @failure 409 "Conflict"
+// @failure 500 "Server error"
+// @router /stacks/webhooks/{webhookID} [post]
 func (handler *Handler) webhookInvoke(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	webhookID, err := retrieveUUIDRouteVariableValue(r, "webhookID")
 	if err != nil {