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

api/http/handler/endpoints/endpoint_association_delete.go

@@ -27,7 +27,7 @@ import (
 // @failure 400 "Invalid request"
 // @failure 404 "Environment(Endpoint) not found"
 // @failure 500 "Server error"
-// @router /api/endpoints/{id}/association [put]
+// @router /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 {

api/http/handler/endpoints/endpoint_dockerhub_status.go

@@ -18,11 +18,27 @@ import (
 )
 
 type dockerhubStatusResponse struct {
+	// Remaiming images to pull
 	Remaining int `json:"remaining"`
-	Limit     int `json:"limit"`
+	// Daily limit
+	Limit int `json:"limit"`
 }
 
-// GET request on /api/endpoints/{id}/dockerhub/{registryId}
+// @id endpointDockerhubStatus
+// @summary fetch docker pull limits
+// @description get docker pull limits for a docker hub registry in the environment
+// @description **Access policy**:
+// @tags endpoints
+// @security jwt
+// @produce json
+// @param id path int true "endpoint ID"
+// @param registryId path int true "registry ID"
+// @success 200 {object} dockerhubStatusResponse "Success"
+// @failure 400 "Invalid request"
+// @failure 403 "Permission denied"
+// @failure 404 "registry or endpoint not found"
+// @failure 500 "Server error"
+// @router /endpoints/{id}/dockerhub/{registryId} [get]
 func (handler *Handler) endpointDockerhubStatus(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {

api/http/handler/endpoints/endpoint_extension_add.go

@@ -29,6 +29,12 @@ func (payload *endpointExtensionAddPayload) Validate(r *http.Request) error {
 	return nil
 }
 
+// @id endpointExtensionAdd
+// @tags endpoints
+// @deprecated
+// @param id path int true "Environment(Endpoint) identifier"
+// @success 204 "Success"
+// @router /endpoints/{id}/extensions [post]
 func (handler *Handler) endpointExtensionAdd(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {

api/http/handler/endpoints/endpoint_extension_remove.go

@@ -12,6 +12,13 @@ import (
 	"github.com/portainer/portainer/api/bolt/errors"
 )
 
+// @id endpointExtensionRemove
+// @tags endpoints
+// @deprecated
+// @param id path int true "Environment(Endpoint) identifier"
+// @param extensionType path string true "Extension Type"
+// @success 204 "Success"
+// @router /endpoints/{id}/extensions/{extensionType} [delete]
 func (handler *Handler) endpointExtensionRemove(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {

api/http/handler/endpoints/endpoint_registries_inspect.go

@@ -12,7 +12,20 @@ import (
 	"github.com/portainer/portainer/api/http/security"
 )
 
-// GET request on /endpoints/{id}/registries/{registryId}
+// @id endpointRegistryInspect
+// @summary get registry for environment
+// @description **Access policy**: authenticated
+// @tags endpoints
+// @security jwt
+// @produce json
+// @param id path int true "identifier"
+// @param registryId path int true "Registry identifier"
+// @success 200 {object} portainer.Registry "Success"
+// @failure 400 "Invalid request"
+// @failure 403 "Permission denied"
+// @failure 404 "Registry not found"
+// @failure 500 "Server error"
+// @router /endpoints/{id}/registries/{registryId} [get]
 func (handler *Handler) endpointRegistryInspect(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {

api/http/handler/endpoints/endpoint_registries_list.go

@@ -13,7 +13,18 @@ import (
 	"github.com/portainer/portainer/api/internal/endpointutils"
 )
 
-// GET request on /endpoints/{id}/registries?namespace
+// @id endpointRegistriesList
+// @summary List Registries on environment
+// @description List all registries based on the current user authorizations in current environment.
+// @description **Access policy**: authenticated
+// @tags endpoints
+// @param namespace query string false "required if kubernetes environment, will show registries by namespace"
+// @security jwt
+// @produce json
+// @param id path int true "Environment(Endpoint) identifier"
+// @success 200 {array} portainer.Registry "Success"
+// @failure 500 "Server error"
+// @router /endpoints/{id}/registries [get]
 func (handler *Handler) endpointRegistriesList(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	securityContext, err := security.RetrieveRestrictedRequestContext(r)
 	if err != nil {

api/http/handler/endpoints/endpoint_registry_access.go

@@ -21,7 +21,22 @@ func (payload *registryAccessPayload) Validate(r *http.Request) error {
 	return nil
 }
 
-// PUT request on /endpoints/{id}/registries/{registryId}
+// @id endpointRegistryAccess
+// @summary update registry access for environment
+// @description **Access policy**: authenticated
+// @tags endpoints
+// @security jwt
+// @accept json
+// @produce json
+// @param id path int true "Environment(Endpoint) identifier"
+// @param registryId path int true "Registry identifier"
+// @param body body registryAccessPayload true "details"
+// @success 204 "Success"
+// @failure 400 "Invalid request"
+// @failure 403 "Permission denied"
+// @failure 404 "Endpoint not found"
+// @failure 500 "Server error"
+// @router /endpoints/{id}/registries/{registryId} [put]
 func (handler *Handler) endpointRegistryAccess(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {

api/http/handler/endpoints/endpoint_settings_update.go

@@ -36,9 +36,9 @@ func (payload *endpointSettingsUpdatePayload) Validate(r *http.Request) error {
 }
 
 // @id EndpointSettingsUpdate
-// @summary Update settings for an environments(endpoints)
-// @description Update settings for an environments(endpoints).
-// @description **Access policy**: administrator
+// @summary Update settings for an environment(endpoint)
+// @description Update settings for an environment(endpoint).
+// @description **Access policy**: authenticated
 // @security jwt
 // @tags endpoints
 // @accept json
@@ -49,7 +49,7 @@ func (payload *endpointSettingsUpdatePayload) Validate(r *http.Request) error {
 // @failure 400 "Invalid request"
 // @failure 404 "Environment(Endpoint) not found"
 // @failure 500 "Server error"
-// @router /api/endpoints/{id}/settings [put]
+// @router /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/endpoints/endpoint_snapshot.go

@@ -12,9 +12,9 @@ import (
 )
 
 // @id EndpointSnapshot
-// @summary Snapshots an environments(endpoints)
-// @description Snapshots an environments(endpoints)
-// @description **Access policy**: restricted
+// @summary Snapshots an environment(endpoint)
+// @description Snapshots an environment(endpoint)
+// @description **Access policy**: administrator
 // @tags endpoints
 // @security jwt
 // @param id path int true "Environment(Endpoint) identifier"

api/http/handler/endpoints/endpoint_update.go

@@ -56,7 +56,7 @@ func (payload *endpointUpdatePayload) Validate(r *http.Request) error {
 // @id EndpointUpdate
 // @summary Update an environment(endpoint)
 // @description Update an environment(endpoint).
-// @description **Access policy**: administrator
+// @description **Access policy**: authenticated
 // @security jwt
 // @tags endpoints
 // @accept json