From 7e9dd012654ad16d6e0d766248b8a70ac725cf0b Mon Sep 17 00:00:00 2001
From: Prabhat Khera <91852476+prabhat-portainer@users.noreply.github.com>
Date: Fri, 19 Apr 2024 15:19:13 +1200
Subject: [PATCH] fix(swagger): swagger docs for http status code 409 [EE-5767]
 (#11535)

---
 api/http/handler/edgegroups/edgegroup_delete.go             | 3 ++-
 api/http/handler/endpoints/endpoint_create.go               | 1 +
 api/http/handler/endpoints/endpoint_update.go               | 1 +
 api/http/handler/registries/registry_create.go              | 1 +
 api/http/handler/registries/registry_update.go              | 2 +-
 api/http/handler/resourcecontrols/resourcecontrol_create.go | 2 +-
 api/http/handler/stacks/create_compose_stack.go             | 1 +
 api/http/handler/stacks/create_kubernetes_stack.go          | 1 +
 api/http/handler/stacks/create_swarm_stack.go               | 1 +
 api/http/handler/stacks/stack_migrate.go                    | 1 +
 api/http/handler/stacks/stack_start.go                      | 1 +
 api/http/handler/stacks/webhook_invoke.go                   | 2 +-
 api/http/handler/tags/tag_create.go                         | 2 +-
 api/http/handler/teams/team_create.go                       | 2 +-
 api/http/handler/webhooks/webhook_create.go                 | 6 +++---
 15 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/api/http/handler/edgegroups/edgegroup_delete.go b/api/http/handler/edgegroups/edgegroup_delete.go
index f6ad932d3..46890dc81 100644
--- a/api/http/handler/edgegroups/edgegroup_delete.go
+++ b/api/http/handler/edgegroups/edgegroup_delete.go
@@ -19,8 +19,9 @@ import (
 // @security jwt
 // @param id path int true "EdgeGroup Id"
 // @success 204
+// @failure 409 "Edge group is in use by an Edge stack or Edge job"
 // @failure 503 "Edge compute features are disabled"
-// @failure 500
+// @failure 500 "Server error"
 // @router /edge_groups/{id} [delete]
 func (handler *Handler) edgeGroupDelete(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	edgeGroupID, err := request.RetrieveNumericRouteVariableValue(r, "id")
diff --git a/api/http/handler/endpoints/endpoint_create.go b/api/http/handler/endpoints/endpoint_create.go
index 12449ab35..a4c0798ca 100644
--- a/api/http/handler/endpoints/endpoint_create.go
+++ b/api/http/handler/endpoints/endpoint_create.go
@@ -201,6 +201,7 @@ func (payload *endpointCreatePayload) Validate(r *http.Request) error {
 // @param Gpus formData string false "List of GPUs - json stringified array of {name, value} structs"
 // @success 200 {object} portainer.Endpoint "Success"
 // @failure 400 "Invalid request"
+// @failure 409 "Name is not unique"
 // @failure 500 "Server error"
 // @router /endpoints [post]
 func (handler *Handler) endpointCreate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
diff --git a/api/http/handler/endpoints/endpoint_update.go b/api/http/handler/endpoints/endpoint_update.go
index 8a1d1a1a5..e62902c9d 100644
--- a/api/http/handler/endpoints/endpoint_update.go
+++ b/api/http/handler/endpoints/endpoint_update.go
@@ -69,6 +69,7 @@ func (payload *endpointUpdatePayload) Validate(r *http.Request) error {
 // @success 200 {object} portainer.Endpoint "Success"
 // @failure 400 "Invalid request"
 // @failure 404 "Environment(Endpoint) not found"
+// @failure 409 "Name is not unique"
 // @failure 500 "Server error"
 // @router /endpoints/{id} [put]
 func (handler *Handler) endpointUpdate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
diff --git a/api/http/handler/registries/registry_create.go b/api/http/handler/registries/registry_create.go
index 2ddf86b56..fd9c18ffb 100644
--- a/api/http/handler/registries/registry_create.go
+++ b/api/http/handler/registries/registry_create.go
@@ -89,6 +89,7 @@ func (payload *registryCreatePayload) Validate(_ *http.Request) error {
 // @param body body registryCreatePayload true "Registry details"
 // @success 200 {object} portainer.Registry "Success"
 // @failure 400 "Invalid request"
+// @failure 409 "Another registry with the same name or same URL & credentials already exists"
 // @failure 500 "Server error"
 // @router /registries [post]
 func (handler *Handler) registryCreate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
diff --git a/api/http/handler/registries/registry_update.go b/api/http/handler/registries/registry_update.go
index 7b6b1967c..ef62375b4 100644
--- a/api/http/handler/registries/registry_update.go
+++ b/api/http/handler/registries/registry_update.go
@@ -52,7 +52,7 @@ func (payload *registryUpdatePayload) Validate(r *http.Request) error {
 // @success 200 {object} portainer.Registry "Success"
 // @failure 400 "Invalid request"
 // @failure 404 "Registry not found"
-// @failure 409 "Another registry with the same URL already exists"
+// @failure 409 "Another registry with the same name or same URL & credentials already exists"
 // @failure 500 "Server error"
 // @router /registries/{id} [put]
 func (handler *Handler) registryUpdate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
diff --git a/api/http/handler/resourcecontrols/resourcecontrol_create.go b/api/http/handler/resourcecontrols/resourcecontrol_create.go
index 38eeed085..fae0c7dd9 100644
--- a/api/http/handler/resourcecontrols/resourcecontrol_create.go
+++ b/api/http/handler/resourcecontrols/resourcecontrol_create.go
@@ -63,7 +63,7 @@ func (payload *resourceControlCreatePayload) Validate(r *http.Request) error {
 // @param body body resourceControlCreatePayload true "Resource control details"
 // @success 200 {object} portainer.ResourceControl "Success"
 // @failure 400 "Invalid request"
-// @failure 409 "Resource control already exists"
+// @failure 409 "A resource control is already associated to this resource"
 // @failure 500 "Server error"
 // @router /resource_controls [post]
 func (handler *Handler) resourceControlCreate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
diff --git a/api/http/handler/stacks/create_compose_stack.go b/api/http/handler/stacks/create_compose_stack.go
index d3c99f79a..9745bdb4a 100644
--- a/api/http/handler/stacks/create_compose_stack.go
+++ b/api/http/handler/stacks/create_compose_stack.go
@@ -229,6 +229,7 @@ func (payload *composeStackFromGitRepositoryPayload) Validate(r *http.Request) e
 // @param body body composeStackFromGitRepositoryPayload true "stack config"
 // @success 200 {object} portainer.Stack
 // @failure 400 "Invalid request"
+// @failure 409 "Stack name or webhook ID already exists"
 // @failure 500 "Server error"
 // @router /stacks/create/standalone/repository [post]
 func (handler *Handler) createComposeStackFromGitRepository(w http.ResponseWriter, r *http.Request, endpoint *portainer.Endpoint, userID portainer.UserID) *httperror.HandlerError {
diff --git a/api/http/handler/stacks/create_kubernetes_stack.go b/api/http/handler/stacks/create_kubernetes_stack.go
index 3cd62c3de..edc28a0fe 100644
--- a/api/http/handler/stacks/create_kubernetes_stack.go
+++ b/api/http/handler/stacks/create_kubernetes_stack.go
@@ -195,6 +195,7 @@ func (handler *Handler) createKubernetesStackFromFileContent(w http.ResponseWrit
 // @param endpointId query int true "Identifier of the environment that will be used to deploy the stack"
 // @success 200 {object} portainer.Stack
 // @failure 400 "Invalid request"
+// @failure 409 "Stack name or webhook ID already exists"
 // @failure 500 "Server error"
 // @router /stacks/create/kubernetes/repository [post]
 func (handler *Handler) createKubernetesStackFromGitRepository(w http.ResponseWriter, r *http.Request, endpoint *portainer.Endpoint, userID portainer.UserID) *httperror.HandlerError {
diff --git a/api/http/handler/stacks/create_swarm_stack.go b/api/http/handler/stacks/create_swarm_stack.go
index de9ae7939..60a26ed81 100644
--- a/api/http/handler/stacks/create_swarm_stack.go
+++ b/api/http/handler/stacks/create_swarm_stack.go
@@ -188,6 +188,7 @@ func createStackPayloadFromSwarmGitPayload(name, swarmID, repoUrl, repoReference
 // @param body body swarmStackFromGitRepositoryPayload true "stack config"
 // @success 200 {object} portainer.Stack
 // @failure 400 "Invalid request"
+// @failure 409 "Stack name or webhook ID already exists"
 // @failure 500 "Server error"
 // @router /stacks/create/swarm/repository [post]
 func (handler *Handler) createSwarmStackFromGitRepository(w http.ResponseWriter, r *http.Request, endpoint *portainer.Endpoint, userID portainer.UserID) *httperror.HandlerError {
diff --git a/api/http/handler/stacks/stack_migrate.go b/api/http/handler/stacks/stack_migrate.go
index 69969478f..d7e34e043 100644
--- a/api/http/handler/stacks/stack_migrate.go
+++ b/api/http/handler/stacks/stack_migrate.go
@@ -46,6 +46,7 @@ func (payload *stackMigratePayload) Validate(r *http.Request) error {
 // @failure 400 "Invalid request"
 // @failure 403 "Permission denied"
 // @failure 404 "Stack not found"
+// @failure 409 "A stack with the same name is already running on the target environment(endpoint)"
 // @failure 500 "Server error"
 // @router /stacks/{id}/migrate [post]
 func (handler *Handler) stackMigrate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
diff --git a/api/http/handler/stacks/stack_start.go b/api/http/handler/stacks/stack_start.go
index 36812bd04..438c7231f 100644
--- a/api/http/handler/stacks/stack_start.go
+++ b/api/http/handler/stacks/stack_start.go
@@ -29,6 +29,7 @@ import (
 // @failure 400 "Invalid request"
 // @failure 403 "Permission denied"
 // @failure 404 "Not found"
+// @failure 409 "Stack name is not unique"
 // @failure 500 "Server error"
 // @router /stacks/{id}/start [post]
 func (handler *Handler) stackStart(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
diff --git a/api/http/handler/stacks/webhook_invoke.go b/api/http/handler/stacks/webhook_invoke.go
index 47762f958..813f932c2 100644
--- a/api/http/handler/stacks/webhook_invoke.go
+++ b/api/http/handler/stacks/webhook_invoke.go
@@ -19,7 +19,7 @@ import (
 // @param webhookID path string true "Stack identifier"
 // @success 200 "Success"
 // @failure 400 "Invalid request"
-// @failure 409 "Conflict"
+// @failure 409 "Autoupdate for the stack isn't available"
 // @failure 500 "Server error"
 // @router /stacks/webhooks/{webhookID} [post]
 func (handler *Handler) webhookInvoke(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
diff --git a/api/http/handler/tags/tag_create.go b/api/http/handler/tags/tag_create.go
index 55e5f55fd..ee5cabcab 100644
--- a/api/http/handler/tags/tag_create.go
+++ b/api/http/handler/tags/tag_create.go
@@ -35,7 +35,7 @@ func (payload *tagCreatePayload) Validate(r *http.Request) error {
 // @produce json
 // @param body body tagCreatePayload true "Tag details"
 // @success 200 {object} portainer.Tag "Success"
-// @failure 409 "Tag name exists"
+// @failure 409 "This name is already associated to a tag"
 // @failure 500 "Server error"
 // @router /tags [post]
 func (handler *Handler) tagCreate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
diff --git a/api/http/handler/teams/team_create.go b/api/http/handler/teams/team_create.go
index d2325a8f1..50f4be323 100644
--- a/api/http/handler/teams/team_create.go
+++ b/api/http/handler/teams/team_create.go
@@ -38,7 +38,7 @@ func (payload *teamCreatePayload) Validate(r *http.Request) error {
 // @param body body teamCreatePayload true "details"
 // @success 200 {object} portainer.Team "Success"
 // @failure 400 "Invalid request"
-// @failure 409 "Team already exists"
+// @failure 409 "A team with the same name already exists"
 // @failure 500 "Server error"
 // @router /teams [post]
 func (handler *Handler) teamCreate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
diff --git a/api/http/handler/webhooks/webhook_create.go b/api/http/handler/webhooks/webhook_create.go
index 6e2a6b348..8845a5a7c 100644
--- a/api/http/handler/webhooks/webhook_create.go
+++ b/api/http/handler/webhooks/webhook_create.go
@@ -45,9 +45,9 @@ func (payload *webhookCreatePayload) Validate(r *http.Request) error {
 // @produce json
 // @param body body webhookCreatePayload true "Webhook data"
 // @success 200 {object} portainer.Webhook
-// @failure 400
-// @failure 409
-// @failure 500
+// @failure 400 "Invalid request"
+// @failure 409 "A webhook for this resource already exists"
+// @failure 500 "Server error"
 // @router /webhooks [post]
 func (handler *Handler) webhookCreate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	var payload webhookCreatePayload