mirror of
https://github.com/portainer/portainer.git
synced 2025-07-24 15:59:41 +02:00
docs(api): document apis with swagger (#4678)
* feat(api): introduce swagger * feat(api): anottate api * chore(api): tag endpoints * chore(api): remove tags * chore(api): add docs for oauth auth * chore(api): document create endpoint api * chore(api): document endpoint inspect and list * chore(api): document endpoint update and snapshots * docs(endpointgroups): document groups api * docs(auth): document auth api * chore(build): introduce a yarn script to build api docs * docs(api): document auth * docs(customtemplates): document customtemplates api * docs(tags): document api * docs(api): document the use of token * docs(dockerhub): document dockerhub api * docs(edgegroups): document edgegroups api * docs(edgejobs): document api * docs(edgestacks): doc api * docs(http/upload): add security * docs(api): document edge templates * docs(edge): document edge jobs * docs(endpointgroups): change description * docs(endpoints): document missing apis * docs(motd): doc api * docs(registries): doc api * docs(resourcecontrol): api doc * docs(role): add swagger docs * docs(settings): add swagger docs * docs(api/status): add swagger docs * docs(api/teammembership): add swagger docs * docs(api/teams): add swagger docs * docs(api/templates): add swagger docs * docs(api/users): add swagger docs * docs(api/webhooks): add swagger docs * docs(api/webscokets): add swagger docs * docs(api/stacks): swagger * docs(api): fix missing apis * docs(swagger): regen * chore(build): remove docs from build * docs(api): update tags * docs(api): document tags * docs(api): add description * docs(api): rename jwt token * docs(api): add info about types * docs(api): document types * docs(api): update request types annotation * docs(api): doc registry and resource control * chore(docs): add snippet * docs(api): add description to role * docs(api): add types for settings * docs(status): add types * style(swagger): remove documented code * docs(http/upload): update docs with types * docs(http/tags): add types * docs(api/custom_templates): add types * docs(api/teammembership): add types * docs(http/teams): add types * docs(http/stacks): add types * docs(edge): add types to edgestack * docs(http/teammembership): remove double returns * docs(api/user): add types * docs(http): fixes to make file built * chore(snippets): add scope to swagger snippet * chore(deps): install swag * chore(swagger): remove handler * docs(api): add description * docs(api): ignore docs folder * docs(api): add contributing guidelines * docs(api): cleanup handler * chore(deps): require swaggo * fix(auth): fix typo * fix(docs): make http ids pascal case * feat(edge): add ids to http handlers * fix(docs): add ids * fix(docs): show correct api version * chore(deps): remove swaggo dependency * chore(docs): add install script for swag
This commit is contained in:
Chaim Lev-Ari
GitHub
parent
90f5a6cd0d
commit
50b57614cf
125 changed files with 8264 additions and 4833 deletions
|
|
@ -25,9 +25,12 @@ func normalizeStackName(name string) string {
|
|||
}
|
||||
|
||||
type composeStackFromFileContentPayload struct {
|
||||
Name string
|
||||
StackFileContent string
|
||||
Env []portainer.Pair
|
||||
// Name of the stack
|
||||
Name string `example:"myStack" validate:"required"`
|
||||
// Content of the Stack file
|
||||
StackFileContent string `example:"version: 3\n services:\n web:\n image:nginx" validate:"required"`
|
||||
// A list of environment variables used during stack deployment
|
||||
Env []portainer.Pair `example:""`
|
||||
}
|
||||
|
||||
func (payload *composeStackFromFileContentPayload) Validate(r *http.Request) error {
|
||||
|
|
@ -103,14 +106,24 @@ func (handler *Handler) createComposeStackFromFileContent(w http.ResponseWriter,
|
|||
}
|
||||
|
||||
type composeStackFromGitRepositoryPayload struct {
|
||||
Name string
|
||||
RepositoryURL string
|
||||
RepositoryReferenceName string
|
||||
RepositoryAuthentication bool
|
||||
RepositoryUsername string
|
||||
RepositoryPassword string
|
||||
ComposeFilePathInRepository string
|
||||
Env []portainer.Pair
|
||||
// Name of the stack
|
||||
Name string `example:"myStack" validate:"required"`
|
||||
|
||||
// URL of a Git repository hosting the Stack file
|
||||
RepositoryURL string `example:"https://github.com/openfaas/faas" validate:"required"`
|
||||
// Reference name of a Git repository hosting the Stack file
|
||||
RepositoryReferenceName string `example:"refs/heads/master"`
|
||||
// Use basic authentication to clone the Git repository
|
||||
RepositoryAuthentication bool `example:"true"`
|
||||
// Username used in basic authentication. Required when RepositoryAuthentication is true.
|
||||
RepositoryUsername string `example:"myGitUsername"`
|
||||
// Password used in basic authentication. Required when RepositoryAuthentication is true.
|
||||
RepositoryPassword string `example:"myGitPassword"`
|
||||
// Path to the Stack file inside the Git repository
|
||||
ComposeFilePathInRepository string `example:"docker-compose.yml" default:"docker-compose.yml"`
|
||||
|
||||
// A list of environment variables used during stack deployment
|
||||
Env []portainer.Pair
|
||||
}
|
||||
|
||||
func (payload *composeStackFromGitRepositoryPayload) Validate(r *http.Request) error {
|
||||
|
|
|
|||
|
|
@ -17,10 +17,14 @@ import (
|
|||
)
|
||||
|
||||
type swarmStackFromFileContentPayload struct {
|
||||
Name string
|
||||
SwarmID string
|
||||
StackFileContent string
|
||||
Env []portainer.Pair
|
||||
// Name of the stack
|
||||
Name string `example:"myStack" validate:"required"`
|
||||
// Swarm cluster identifier
|
||||
SwarmID string `example:"jpofkc0i9uo9wtx1zesuk649w" validate:"required"`
|
||||
// Content of the Stack file
|
||||
StackFileContent string `example:"version: 3\n services:\n web:\n image:nginx" validate:"required"`
|
||||
// A list of environment variables used during stack deployment
|
||||
Env []portainer.Pair
|
||||
}
|
||||
|
||||
func (payload *swarmStackFromFileContentPayload) Validate(r *http.Request) error {
|
||||
|
|
@ -99,15 +103,25 @@ func (handler *Handler) createSwarmStackFromFileContent(w http.ResponseWriter, r
|
|||
}
|
||||
|
||||
type swarmStackFromGitRepositoryPayload struct {
|
||||
Name string
|
||||
SwarmID string
|
||||
Env []portainer.Pair
|
||||
RepositoryURL string
|
||||
RepositoryReferenceName string
|
||||
RepositoryAuthentication bool
|
||||
RepositoryUsername string
|
||||
RepositoryPassword string
|
||||
ComposeFilePathInRepository string
|
||||
// Name of the stack
|
||||
Name string `example:"myStack" validate:"required"`
|
||||
// Swarm cluster identifier
|
||||
SwarmID string `example:"jpofkc0i9uo9wtx1zesuk649w" validate:"required"`
|
||||
// A list of environment variables used during stack deployment
|
||||
Env []portainer.Pair
|
||||
|
||||
// URL of a Git repository hosting the Stack file
|
||||
RepositoryURL string `example:"https://github.com/openfaas/faas" validate:"required"`
|
||||
// Reference name of a Git repository hosting the Stack file
|
||||
RepositoryReferenceName string `example:"refs/heads/master"`
|
||||
// Use basic authentication to clone the Git repository
|
||||
RepositoryAuthentication bool `example:"true"`
|
||||
// Username used in basic authentication. Required when RepositoryAuthentication is true.
|
||||
RepositoryUsername string `example:"myGitUsername"`
|
||||
// Password used in basic authentication. Required when RepositoryAuthentication is true.
|
||||
RepositoryPassword string `example:"myGitPassword"`
|
||||
// Path to the Stack file inside the Git repository
|
||||
ComposeFilePathInRepository string `example:"docker-compose.yml" default:"docker-compose.yml"`
|
||||
}
|
||||
|
||||
func (payload *swarmStackFromGitRepositoryPayload) Validate(r *http.Request) error {
|
||||
|
|
|
|||
|
|
@ -29,7 +29,29 @@ func (handler *Handler) cleanUp(stack *portainer.Stack, doCleanUp *bool) error {
|
|||
return nil
|
||||
}
|
||||
|
||||
// POST request on /api/stacks?type=<type>&method=<method>&endpointId=<endpointId>
|
||||
// @id StackCreate
|
||||
// @summary Deploy a new stack
|
||||
// @description Deploy a new stack into a Docker environment specified via the endpoint identifier.
|
||||
// @description **Access policy**: restricted
|
||||
// @tags stacks
|
||||
// @security jwt
|
||||
// @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)
|
||||
// @param endpointId query int true "Identifier of the endpoint that will be used to deploy the stack"
|
||||
// @param body_swarm_string body swarmStackFromFileContentPayload false "Required when using method=string and type=1"
|
||||
// @param body_swarm_repository body swarmStackFromGitRepositoryPayload false "Required when using method=repository and type=1"
|
||||
// @param body_compose_string body composeStackFromFileContentPayload false "Required when using method=string and type=2"
|
||||
// @param body_compose_repository body composeStackFromGitRepositoryPayload false "Required when using method=repository and type=2"
|
||||
// @param Name formData string false "Name of the stack. required when method is file"
|
||||
// @param SwarmID formData string false "Swarm cluster identifier. Required when method equals file and type equals 1. required when method is file"
|
||||
// @param Env formData string false "Environment variables passed during deployment, represented as a JSON array [{'name': 'name', 'value': 'value'}]. Optional, used when method equals file and type equals 1."
|
||||
// @param file formData file false "Stack file. required when method is file"
|
||||
// @success 200 {object} portainer.CustomTemplate
|
||||
// @failure 400 "Invalid request"
|
||||
// @failure 500 "Server error"
|
||||
// @router /stacks [post]
|
||||
func (handler *Handler) stackCreate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
|
||||
stackType, err := request.RetrieveNumericQueryParameter(r, "type", false)
|
||||
if err != nil {
|
||||
|
|
|
|||
|
|
@ -14,9 +14,21 @@ import (
|
|||
"github.com/portainer/portainer/api/http/security"
|
||||
)
|
||||
|
||||
// DELETE request on /api/stacks/:id?external=<external>&endpointId=<endpointId>
|
||||
// If the external query parameter is set to true, the id route variable is expected to be
|
||||
// the name of an external stack as a string.
|
||||
// @id StackDelete
|
||||
// @summary Remove a stack
|
||||
// @description Remove a stack.
|
||||
// @description **Access policy**: restricted
|
||||
// @tags stacks
|
||||
// @security jwt
|
||||
// @param id path int true "Stack identifier"
|
||||
// @param external query boolean false "Set to true to delete an external stack. Only external Swarm stacks are supported"
|
||||
// @param endpointId query int false "Endpoint identifier used to remove an external stack (required when external is set to true)"
|
||||
// @success 204 "Success"
|
||||
// @failure 400 "Invalid request"
|
||||
// @failure 403 "Permission denied"
|
||||
// @failure 404 " not found"
|
||||
// @failure 500 "Server error"
|
||||
// @router /stacks/{id} [delete]
|
||||
func (handler *Handler) stackDelete(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
|
||||
stackID, err := request.RetrieveRouteVariableValue(r, "id")
|
||||
if err != nil {
|
||||
|
|
|
|||
|
|
@ -7,17 +7,31 @@ import (
|
|||
httperror "github.com/portainer/libhttp/error"
|
||||
"github.com/portainer/libhttp/request"
|
||||
"github.com/portainer/libhttp/response"
|
||||
"github.com/portainer/portainer/api"
|
||||
portainer "github.com/portainer/portainer/api"
|
||||
bolterrors "github.com/portainer/portainer/api/bolt/errors"
|
||||
"github.com/portainer/portainer/api/http/errors"
|
||||
"github.com/portainer/portainer/api/http/security"
|
||||
)
|
||||
|
||||
type stackFileResponse struct {
|
||||
StackFileContent string `json:"StackFileContent"`
|
||||
// Content of the Stack file
|
||||
StackFileContent string `json:"StackFileContent" example:"version: 3\n services:\n web:\n image:nginx"`
|
||||
}
|
||||
|
||||
// GET request on /api/stacks/:id/file
|
||||
// @id StackFileInspect
|
||||
// @summary Retrieve the content of the Stack file for the specified stack
|
||||
// @description Get Stack file content.
|
||||
// @description **Access policy**: restricted
|
||||
// @tags stacks
|
||||
// @security jwt
|
||||
// @produce json
|
||||
// @param id path int true "Stack identifier"
|
||||
// @success 200 {object} stackFileResponse "Success"
|
||||
// @failure 400 "Invalid request"
|
||||
// @failure 403 "Permission denied"
|
||||
// @failure 404 "Stack not found"
|
||||
// @failure 500 "Server error"
|
||||
// @router /stacks/{id}/file [get]
|
||||
func (handler *Handler) stackFile(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
|
||||
stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")
|
||||
if err != nil {
|
||||
|
|
|
|||
|
|
@ -6,13 +6,26 @@ import (
|
|||
httperror "github.com/portainer/libhttp/error"
|
||||
"github.com/portainer/libhttp/request"
|
||||
"github.com/portainer/libhttp/response"
|
||||
"github.com/portainer/portainer/api"
|
||||
portainer "github.com/portainer/portainer/api"
|
||||
bolterrors "github.com/portainer/portainer/api/bolt/errors"
|
||||
"github.com/portainer/portainer/api/http/errors"
|
||||
"github.com/portainer/portainer/api/http/security"
|
||||
)
|
||||
|
||||
// GET request on /api/stacks/:id
|
||||
// @id StackInspect
|
||||
// @summary Inspect a stack
|
||||
// @description Retrieve details about a stack.
|
||||
// @description **Access policy**: restricted
|
||||
// @tags stacks
|
||||
// @security jwt
|
||||
// @produce json
|
||||
// @param id path int true "Stack identifier"
|
||||
// @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} [get]
|
||||
func (handler *Handler) stackInspect(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
|
||||
stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")
|
||||
if err != nil {
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ import (
|
|||
httperror "github.com/portainer/libhttp/error"
|
||||
"github.com/portainer/libhttp/request"
|
||||
"github.com/portainer/libhttp/response"
|
||||
"github.com/portainer/portainer/api"
|
||||
portainer "github.com/portainer/portainer/api"
|
||||
"github.com/portainer/portainer/api/http/security"
|
||||
"github.com/portainer/portainer/api/internal/authorization"
|
||||
)
|
||||
|
|
@ -16,7 +16,20 @@ type stackListOperationFilters struct {
|
|||
EndpointID int `json:"EndpointID"`
|
||||
}
|
||||
|
||||
// GET request on /api/stacks?(filters=<filters>)
|
||||
// @id StackList
|
||||
// @summary List stacks
|
||||
// @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
|
||||
// @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."
|
||||
// @success 200 {array} portainer.Stack "Success"
|
||||
// @success 204 "Success"
|
||||
// @failure 400 "Invalid request"
|
||||
// @failure 500 "Server error"
|
||||
// @router /stacks [get]
|
||||
func (handler *Handler) stackList(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
|
||||
var filters stackListOperationFilters
|
||||
err := request.RetrieveJSONQueryParameter(r, "filters", &filters, true)
|
||||
|
|
|
|||
|
|
@ -7,16 +7,19 @@ import (
|
|||
httperror "github.com/portainer/libhttp/error"
|
||||
"github.com/portainer/libhttp/request"
|
||||
"github.com/portainer/libhttp/response"
|
||||
"github.com/portainer/portainer/api"
|
||||
portainer "github.com/portainer/portainer/api"
|
||||
bolterrors "github.com/portainer/portainer/api/bolt/errors"
|
||||
httperrors "github.com/portainer/portainer/api/http/errors"
|
||||
"github.com/portainer/portainer/api/http/security"
|
||||
)
|
||||
|
||||
type stackMigratePayload struct {
|
||||
EndpointID int
|
||||
SwarmID string
|
||||
Name string
|
||||
// Endpoint identifier of the target endpoint where the stack will be relocated
|
||||
EndpointID int `example:"2" validate:"required"`
|
||||
// Swarm cluster identifier, must match the identifier of the cluster where the stack will be relocated
|
||||
SwarmID string `example:"jpofkc0i9uo9wtx1zesuk649w"`
|
||||
// If provided will rename the migrated stack
|
||||
Name string `example:"new-stack"`
|
||||
}
|
||||
|
||||
func (payload *stackMigratePayload) Validate(r *http.Request) error {
|
||||
|
|
@ -26,7 +29,22 @@ func (payload *stackMigratePayload) Validate(r *http.Request) error {
|
|||
return nil
|
||||
}
|
||||
|
||||
// POST request on /api/stacks/:id/migrate?endpointId=<endpointId>
|
||||
// @id StackMigrate
|
||||
// @summary Migrate a stack to another endpoint
|
||||
// @description Migrate a stack from an endpoint to another endpoint. It will re-create the stack inside the target endpoint before removing the original stack.
|
||||
// @description **Access policy**: restricted
|
||||
// @tags stacks
|
||||
// @security jwt
|
||||
// @produce json
|
||||
// @param id path int true "Stack identifier"
|
||||
// @param endpointId query int false "Stacks created before version 1.18.0 might not have an associated endpoint identifier. Use this optional parameter to set the endpoint identifier used by the stack."
|
||||
// @param body body stackMigratePayload true "Stack migration details"
|
||||
// @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}/migrate [post]
|
||||
func (handler *Handler) stackMigrate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
|
||||
stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")
|
||||
if err != nil {
|
||||
|
|
|
|||
|
|
@ -14,7 +14,19 @@ import (
|
|||
bolterrors "github.com/portainer/portainer/api/bolt/errors"
|
||||
)
|
||||
|
||||
// POST request on /api/stacks/:id/start
|
||||
// @id StackStart
|
||||
// @summary Starts a stopped Stack
|
||||
// @description Starts a stopped Stack.
|
||||
// @description **Access policy**: restricted
|
||||
// @tags stacks
|
||||
// @security jwt
|
||||
// @param id path int true "Stack identifier"
|
||||
// @success 200 {object} portainer.Stack "Success"
|
||||
// @failure 400 "Invalid request"
|
||||
// @failure 403 "Permission denied"
|
||||
// @failure 404 " not found"
|
||||
// @failure 500 "Server error"
|
||||
// @router /stacks/{id}/start [post]
|
||||
func (handler *Handler) stackStart(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
|
||||
stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")
|
||||
if err != nil {
|
||||
|
|
|
|||
|
|
@ -7,14 +7,25 @@ import (
|
|||
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"
|
||||
httperrors "github.com/portainer/portainer/api/http/errors"
|
||||
"github.com/portainer/portainer/api/http/security"
|
||||
)
|
||||
|
||||
// POST request on /api/stacks/:id/stop
|
||||
// @id StackStop
|
||||
// @summary Stops a stopped Stack
|
||||
// @description Stops a stopped Stack.
|
||||
// @description **Access policy**: restricted
|
||||
// @tags stacks
|
||||
// @security jwt
|
||||
// @param id path int true "Stack identifier"
|
||||
// @success 200 {object} portainer.Stack "Success"
|
||||
// @failure 400 "Invalid request"
|
||||
// @failure 403 "Permission denied"
|
||||
// @failure 404 " not found"
|
||||
// @failure 500 "Server error"
|
||||
// @router /stacks/{id}/stop [post]
|
||||
func (handler *Handler) stackStop(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
|
||||
stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")
|
||||
if err != nil {
|
||||
|
|
|
|||
|
|
@ -17,8 +17,10 @@ import (
|
|||
)
|
||||
|
||||
type updateComposeStackPayload struct {
|
||||
StackFileContent string
|
||||
Env []portainer.Pair
|
||||
// New content of the Stack file
|
||||
StackFileContent string `example:"version: 3\n services:\n web:\n image:nginx"`
|
||||
// A list of environment variables used during stack deployment
|
||||
Env []portainer.Pair
|
||||
}
|
||||
|
||||
func (payload *updateComposeStackPayload) Validate(r *http.Request) error {
|
||||
|
|
@ -29,9 +31,12 @@ func (payload *updateComposeStackPayload) Validate(r *http.Request) error {
|
|||
}
|
||||
|
||||
type updateSwarmStackPayload struct {
|
||||
StackFileContent string
|
||||
Env []portainer.Pair
|
||||
Prune bool
|
||||
// New content of the Stack file
|
||||
StackFileContent string `example:"version: 3\n services:\n web:\n image:nginx"`
|
||||
// A list of environment variables used during stack deployment
|
||||
Env []portainer.Pair
|
||||
// Prune services that are no longer referenced (only available for Swarm stacks)
|
||||
Prune bool `example:"true"`
|
||||
}
|
||||
|
||||
func (payload *updateSwarmStackPayload) Validate(r *http.Request) error {
|
||||
|
|
@ -41,7 +46,23 @@ func (payload *updateSwarmStackPayload) Validate(r *http.Request) error {
|
|||
return nil
|
||||
}
|
||||
|
||||
// PUT request on /api/stacks/:id?endpointId=<endpointId>
|
||||
// @id StackUpdate
|
||||
// @summary Update a stack
|
||||
// @description Update a stack.
|
||||
// @description **Access policy**: restricted
|
||||
// @tags stacks
|
||||
// @security jwt
|
||||
// @accept json
|
||||
// @produce json
|
||||
// @param id path int true "Stack identifier"
|
||||
// @param endpointId query int false "Stacks created before version 1.18.0 might not have an associated endpoint identifier. Use this optional parameter to set the endpoint identifier used by the stack."
|
||||
// @param body body updateSwarmStackPayload true "Stack details"
|
||||
// @success 200 {object} portainer.Stack "Success"
|
||||
// @failure 400 "Invalid request"
|
||||
// @failure 403 "Permission denied"
|
||||
// @failure 404 " not found"
|
||||
// @failure 500 "Server error"
|
||||
// @router /stacks/{id} [put]
|
||||
func (handler *Handler) stackUpdate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
|
||||
stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")
|
||||
if err != nil {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue