mirror of https://github.com/portainer/portainer
docs(api): document the stack management endpoint (#1557)
Anthony Lapenna
GitHub
parent
d2f3309842
commit
35892525ff
389
api/swagger.yaml
389
api/swagger.yaml
|
|
@ -77,6 +77,8 @@ tags:
|
|||
description: "Manage Portainer settings"
|
||||
- name: "status"
|
||||
description: "Information about the Portainer instance"
|
||||
- name: "stacks"
|
||||
description: "Manage Docker stacks"
|
||||
- name: "users"
|
||||
description: "Manage users"
|
||||
- name: "teams"
|
||||
|
|
@ -436,6 +438,285 @@ paths:
|
|||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
|
||||
/endpoints/{endpointId}/stacks:
|
||||
get:
|
||||
tags:
|
||||
- "stacks"
|
||||
summary: "List stacks"
|
||||
description: |
|
||||
List all stacks based on the current user authorizations.
|
||||
Will return all stacks if using an administrator account otherwise it
|
||||
will only return the list of stacks the user have access to.
|
||||
**Access policy**: restricted
|
||||
operationId: "StackList"
|
||||
produces:
|
||||
- "application/json"
|
||||
parameters:
|
||||
- name: "endpointId"
|
||||
in: "path"
|
||||
description: "Endpoint identifier"
|
||||
required: true
|
||||
type: "integer"
|
||||
responses:
|
||||
200:
|
||||
description: "Success"
|
||||
schema:
|
||||
$ref: "#/definitions/StackListResponse"
|
||||
403:
|
||||
description: "Unauthorized"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Access denied to resource"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
post:
|
||||
tags:
|
||||
- "stacks"
|
||||
summary: "Deploy a new stack"
|
||||
description: |
|
||||
Deploy a new stack into a Docker environment specified via the endpoint identifier.
|
||||
**Access policy**: restricted
|
||||
operationId: "StackCreate"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
parameters:
|
||||
- name: "endpointId"
|
||||
in: "path"
|
||||
description: "Endpoint identifier"
|
||||
required: true
|
||||
type: "integer"
|
||||
- name: "method"
|
||||
in: "query"
|
||||
description: "Stack deployment method. Possible values: string or repository."
|
||||
required: true
|
||||
type: "string"
|
||||
- in: "body"
|
||||
name: "body"
|
||||
description: "Stack details. Used when"
|
||||
required: true
|
||||
schema:
|
||||
$ref: "#/definitions/StackCreateRequest"
|
||||
responses:
|
||||
200:
|
||||
description: "Success"
|
||||
schema:
|
||||
$ref: "#/definitions/StackCreateResponse"
|
||||
400:
|
||||
description: "Invalid request"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Invalid request data format"
|
||||
404:
|
||||
description: "Endpoint not found"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Endpoint not found"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
/endpoints/{endpointId}/stacks/{id}:
|
||||
get:
|
||||
tags:
|
||||
- "stacks"
|
||||
summary: "Inspect a stack"
|
||||
description: |
|
||||
Retrieve details about a stack.
|
||||
**Access policy**: restricted
|
||||
operationId: "StackInspect"
|
||||
produces:
|
||||
- "application/json"
|
||||
parameters:
|
||||
- name: "endpointId"
|
||||
in: "path"
|
||||
description: "Endpoint identifier"
|
||||
required: true
|
||||
type: "integer"
|
||||
- name: "id"
|
||||
in: "path"
|
||||
description: "Stack identifier"
|
||||
required: true
|
||||
type: "string"
|
||||
responses:
|
||||
200:
|
||||
description: "Success"
|
||||
schema:
|
||||
$ref: "#/definitions/Stack"
|
||||
400:
|
||||
description: "Invalid request"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Invalid request"
|
||||
403:
|
||||
description: "Unauthorized"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
404:
|
||||
description: "Stack not found"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Stack not found"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
put:
|
||||
tags:
|
||||
- "stacks"
|
||||
summary: "Update a stack"
|
||||
description: |
|
||||
Update a stack.
|
||||
**Access policy**: restricted
|
||||
operationId: "StackUpdate"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
parameters:
|
||||
- name: "endpointId"
|
||||
in: "path"
|
||||
description: "Endpoint identifier"
|
||||
required: true
|
||||
type: "integer"
|
||||
- name: "id"
|
||||
in: "path"
|
||||
description: "Stack identifier"
|
||||
required: true
|
||||
type: "string"
|
||||
- in: "body"
|
||||
name: "body"
|
||||
description: "Stack details"
|
||||
required: true
|
||||
schema:
|
||||
$ref: "#/definitions/StackUpdateRequest"
|
||||
responses:
|
||||
200:
|
||||
description: "Success"
|
||||
400:
|
||||
description: "Invalid request"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Invalid request data format"
|
||||
404:
|
||||
description: "Stack not found"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Stack not found"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
delete:
|
||||
tags:
|
||||
- "stacks"
|
||||
summary: "Remove a stack"
|
||||
description: |
|
||||
Remove a stack.
|
||||
**Access policy**: restricted
|
||||
operationId: "StackDelete"
|
||||
parameters:
|
||||
- name: "endpointId"
|
||||
in: "path"
|
||||
description: "Endpoint identifier"
|
||||
required: true
|
||||
type: "integer"
|
||||
- name: "id"
|
||||
in: "path"
|
||||
description: "Stack identifier"
|
||||
required: true
|
||||
type: "string"
|
||||
responses:
|
||||
200:
|
||||
description: "Success"
|
||||
400:
|
||||
description: "Invalid request"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Invalid request"
|
||||
403:
|
||||
description: "Unauthorized"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
404:
|
||||
description: "Stack not found"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Stack not found"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
/endpoints/{endpointId}/stacks/{id}/stackfile:
|
||||
get:
|
||||
tags:
|
||||
- "stacks"
|
||||
summary: "Retrieve the content of the Stack file for the specified stack"
|
||||
description: |
|
||||
Get Stack file content.
|
||||
**Access policy**: restricted
|
||||
operationId: "StackFileInspect"
|
||||
produces:
|
||||
- "application/json"
|
||||
parameters:
|
||||
- name: "endpointId"
|
||||
in: "path"
|
||||
description: "Endpoint identifier"
|
||||
required: true
|
||||
type: "integer"
|
||||
- name: "id"
|
||||
in: "path"
|
||||
description: "Stack identifier"
|
||||
required: true
|
||||
type: "string"
|
||||
responses:
|
||||
200:
|
||||
description: "Success"
|
||||
schema:
|
||||
$ref: "#/definitions/StackFileInspectResponse"
|
||||
400:
|
||||
description: "Invalid request"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Invalid request"
|
||||
403:
|
||||
description: "Unauthorized"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
404:
|
||||
description: "Stack not found"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Stack not found"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
/registries:
|
||||
get:
|
||||
tags:
|
||||
|
|
@ -536,7 +817,7 @@ paths:
|
|||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Endpoint not found"
|
||||
err: "Registry not found"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
|
|
@ -593,13 +874,6 @@ paths:
|
|||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
503:
|
||||
description: "Endpoint management disabled"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Endpoint management is disabled"
|
||||
delete:
|
||||
tags:
|
||||
- "registries"
|
||||
|
|
@ -1883,7 +2157,7 @@ definitions:
|
|||
DisplayDonationHeader:
|
||||
type: "boolean"
|
||||
example: true
|
||||
description: "Whether to display or not the donation message in the header."\
|
||||
description: "Whether to display or not the donation message in the header."
|
||||
DisplayExternalContributors:
|
||||
type: "boolean"
|
||||
example: false
|
||||
|
|
@ -2612,3 +2886,100 @@ definitions:
|
|||
type: "string"
|
||||
example: "nginx:latest"
|
||||
description: "The Docker image associated to the template"
|
||||
StackCreateRequest:
|
||||
type: "object"
|
||||
required:
|
||||
- "Name"
|
||||
- "SwarmID"
|
||||
properties:
|
||||
Name:
|
||||
type: "string"
|
||||
example: "myStack"
|
||||
description: "Name of the stack"
|
||||
SwarmID:
|
||||
type: "string"
|
||||
example: "jpofkc0i9uo9wtx1zesuk649w"
|
||||
description: "Cluster identifier of the Swarm cluster"
|
||||
StackFileContent:
|
||||
type: "string"
|
||||
example: "version: 3\n services:\n web:\n image:nginx"
|
||||
description: "Content of the Stack file. Required when using the 'string' deployment method."
|
||||
GitRepository:
|
||||
type: "string"
|
||||
example: "https://github.com/openfaas/faas"
|
||||
description: "URL of a public Git repository hosting the Stack file. Required when using the 'repository' deployment method."
|
||||
PathInRepository:
|
||||
type: "string"
|
||||
example: "docker-compose.yml"
|
||||
description: "Path to the Stack file inside the Git repository. Required when using the 'repository' deployment method."
|
||||
Env:
|
||||
type: "array"
|
||||
description: "A list of environment variables used during stack deployment"
|
||||
items:
|
||||
$ref: "#/definitions/Stack_Env"
|
||||
Stack_Env:
|
||||
properties:
|
||||
name:
|
||||
type: "string"
|
||||
example: "MYSQL_ROOT_PASSWORD"
|
||||
value:
|
||||
type: "string"
|
||||
example: "password"
|
||||
StackCreateResponse:
|
||||
type: "object"
|
||||
properties:
|
||||
Id:
|
||||
type: "string"
|
||||
example: "myStack_jpofkc0i9uo9wtx1zesuk649w"
|
||||
description: "Id of the stack"
|
||||
StackListResponse:
|
||||
type: "array"
|
||||
items:
|
||||
$ref: "#/definitions/Stack"
|
||||
Stack:
|
||||
type: "object"
|
||||
properties:
|
||||
Id:
|
||||
type: "string"
|
||||
example: "myStack_jpofkc0i9uo9wtx1zesuk649w"
|
||||
description: "Stack identifier"
|
||||
Name:
|
||||
type: "string"
|
||||
example: "myStack"
|
||||
description: "Stack name"
|
||||
EntryPoint:
|
||||
type: "string"
|
||||
example: "docker-compose.yml"
|
||||
description: "Path to the Stack file"
|
||||
SwarmID:
|
||||
type: "string"
|
||||
example: "jpofkc0i9uo9wtx1zesuk649w"
|
||||
description: "Cluster identifier of the Swarm cluster where the stack is deployed"
|
||||
ProjectPath:
|
||||
type: "string"
|
||||
example: "/data/compose/myStack_jpofkc0i9uo9wtx1zesuk649w"
|
||||
description: "Path on disk to the repository hosting the Stack file"
|
||||
Env:
|
||||
type: "array"
|
||||
description: "A list of environment variables used during stack deployment"
|
||||
items:
|
||||
$ref: "#/definitions/Stack_Env"
|
||||
StackUpdateRequest:
|
||||
type: "object"
|
||||
properties:
|
||||
StackFileContent:
|
||||
type: "string"
|
||||
example: "version: 3\n services:\n web:\n image:nginx"
|
||||
description: "New content of the Stack file."
|
||||
Env:
|
||||
type: "array"
|
||||
description: "A list of environment variables used during stack deployment"
|
||||
items:
|
||||
$ref: "#/definitions/Stack_Env"
|
||||
StackFileInspectResponse:
|
||||
type: "object"
|
||||
properties:
|
||||
StackFileContent:
|
||||
type: "string"
|
||||
example: "version: 3\n services:\n web:\n image:nginx"
|
||||
description: "Content of the Stack file."
|
||||
|
|
|
|||
Loading…
Reference in New Issue