mirror of https://github.com/portainer/portainer
docs(api): update swagger documentation
Anthony Lapenna
parent
e5f092058b
commit
67de71a18f
352
api/swagger.yaml
352
api/swagger.yaml
|
|
@ -69,10 +69,14 @@ tags:
|
|||
description: "Manage Docker environments"
|
||||
- name: "endpoint_groups"
|
||||
description: "Manage endpoint groups"
|
||||
- name: "extensions"
|
||||
description: "Manage extensions"
|
||||
- name: "registries"
|
||||
description: "Manage Docker registries"
|
||||
- name: "resource_controls"
|
||||
description: "Manage access control on Docker resources"
|
||||
- name: "roles"
|
||||
description: "Manage roles"
|
||||
- name: "settings"
|
||||
description: "Manage Portainer settings"
|
||||
- name: "status"
|
||||
|
|
@ -741,6 +745,196 @@ paths:
|
|||
examples:
|
||||
application/json:
|
||||
err: "EndpointGroup management is disabled"
|
||||
/extensions:
|
||||
get:
|
||||
tags:
|
||||
- "extensions"
|
||||
summary: "List extensions"
|
||||
description: |
|
||||
List all extensions registered inside Portainer. If the store parameter is set to true,
|
||||
will retrieve extensions details from the online repository.
|
||||
**Access policy**: administrator
|
||||
operationId: "ExtensionList"
|
||||
produces:
|
||||
- "application/json"
|
||||
security:
|
||||
- jwt: []
|
||||
parameters:
|
||||
- name: "store"
|
||||
in: "query"
|
||||
description: "Retrieve online information about extensions. Possible values: true or false."
|
||||
required: false
|
||||
type: "boolean"
|
||||
responses:
|
||||
200:
|
||||
description: "Success"
|
||||
schema:
|
||||
$ref: "#/definitions/ExtensionListResponse"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
post:
|
||||
tags:
|
||||
- "extensions"
|
||||
summary: "Enable an extension"
|
||||
description: |
|
||||
Enable an extension.
|
||||
**Access policy**: administrator
|
||||
operationId: "ExtensionCreate"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
security:
|
||||
- jwt: []
|
||||
parameters:
|
||||
- in: "body"
|
||||
name: "body"
|
||||
description: "Extension details"
|
||||
required: true
|
||||
schema:
|
||||
$ref: "#/definitions/ExtensionCreateRequest"
|
||||
responses:
|
||||
204:
|
||||
description: "Success"
|
||||
400:
|
||||
description: "Invalid request"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Invalid request data format"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
/extensions/{id}:
|
||||
get:
|
||||
tags:
|
||||
- "extensions"
|
||||
summary: "Inspect an extension"
|
||||
description: |
|
||||
Retrieve details abount an extension.
|
||||
**Access policy**: administrator
|
||||
operationId: "ExtensionInspect"
|
||||
produces:
|
||||
- "application/json"
|
||||
security:
|
||||
- jwt: []
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
description: "extension identifier"
|
||||
required: true
|
||||
type: "integer"
|
||||
responses:
|
||||
200:
|
||||
description: "Success"
|
||||
schema:
|
||||
$ref: "#/definitions/Extension"
|
||||
400:
|
||||
description: "Invalid request"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Invalid request"
|
||||
404:
|
||||
description: "Extension not found"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Extension not found"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
put:
|
||||
tags:
|
||||
- "extensions"
|
||||
summary: "Update an extension"
|
||||
description: |
|
||||
Update an extension to a specific version of the extension.
|
||||
**Access policy**: administrator
|
||||
operationId: "ExtensionUpdate"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
security:
|
||||
- jwt: []
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
description: "Extension identifier"
|
||||
required: true
|
||||
type: "integer"
|
||||
- in: "body"
|
||||
name: "body"
|
||||
description: "Extension details"
|
||||
required: true
|
||||
schema:
|
||||
$ref: "#/definitions/ExtensionUpdateRequest"
|
||||
responses:
|
||||
204:
|
||||
description: "Success"
|
||||
400:
|
||||
description: "Invalid request"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Invalid request data format"
|
||||
404:
|
||||
description: "Extension not found"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Extension not found"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
delete:
|
||||
tags:
|
||||
- "extensions"
|
||||
summary: "Disable an extension"
|
||||
description: |
|
||||
Disable an extension.
|
||||
**Access policy**: administrator
|
||||
operationId: "ExtensionDelete"
|
||||
security:
|
||||
- jwt: []
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
description: "Extension identifier"
|
||||
required: true
|
||||
type: "integer"
|
||||
responses:
|
||||
204:
|
||||
description: "Success"
|
||||
400:
|
||||
description: "Invalid request"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Invalid request"
|
||||
404:
|
||||
description: "Extension not found"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
examples:
|
||||
application/json:
|
||||
err: "Extension not found"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
/registries:
|
||||
get:
|
||||
tags:
|
||||
|
|
@ -1098,6 +1292,29 @@ paths:
|
|||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
/roles:
|
||||
get:
|
||||
tags:
|
||||
- "roles"
|
||||
summary: "List roles"
|
||||
description: |
|
||||
List all roles available for use with the RBAC extension.
|
||||
**Access policy**: administrator
|
||||
operationId: "RoleList"
|
||||
produces:
|
||||
- "application/json"
|
||||
security:
|
||||
- jwt: []
|
||||
parameters: []
|
||||
responses:
|
||||
200:
|
||||
description: "Success"
|
||||
schema:
|
||||
$ref: "#/definitions/RoleListResponse"
|
||||
500:
|
||||
description: "Server error"
|
||||
schema:
|
||||
$ref: "#/definitions/GenericError"
|
||||
/settings:
|
||||
get:
|
||||
tags:
|
||||
|
|
@ -4335,3 +4552,138 @@ definitions:
|
|||
type: "string"
|
||||
example: "version: 3\n services:\n web:\n image:nginx"
|
||||
description: "Content of the Stack file."
|
||||
LicenseInformation:
|
||||
type: "object"
|
||||
properties:
|
||||
LicenseKey:
|
||||
type: "string"
|
||||
description: "License key"
|
||||
example: "1-uKmVwboSWVIZv5URmE0VRkpbPX0rrCVeDxJl97LZ0piltw2SU28DSrNwPZAHCEAwB2SeKm6BCFcVwzGMBEixKQ"
|
||||
Company:
|
||||
type: "string"
|
||||
description: "Company associated to the license"
|
||||
example: "Portainer.io"
|
||||
Expiration:
|
||||
type: "string"
|
||||
description: "License expiry date"
|
||||
example: "2077-07-07"
|
||||
Valid:
|
||||
type: "boolean"
|
||||
description: "Is the license valid"
|
||||
example: "true"
|
||||
Extension:
|
||||
type: "object"
|
||||
properties:
|
||||
Id:
|
||||
type: "integer"
|
||||
example: 1
|
||||
description: "Extension identifier"
|
||||
Name:
|
||||
type: "string"
|
||||
example: "Registry Manager"
|
||||
description: "Extension name"
|
||||
Enabled:
|
||||
type: "boolean"
|
||||
example: "true"
|
||||
description: "Is the extension enabled"
|
||||
ShortDescription:
|
||||
type: "string"
|
||||
description: "Short description about the extension"
|
||||
example: "Enable in-app registry management"
|
||||
DescriptionURL:
|
||||
type: "string"
|
||||
description: "URL to the file containing the extension description"
|
||||
example: https://portainer-io-assets.sfo2.digitaloceanspaces.com/description_registry_manager.html"
|
||||
Available:
|
||||
type: "boolean"
|
||||
description: "Is the extension available for download and activation"
|
||||
example: "true"
|
||||
Images:
|
||||
type: "array"
|
||||
description: "List of screenshot URLs"
|
||||
items:
|
||||
type: "string"
|
||||
example: "https://portainer-io-assets.sfo2.digitaloceanspaces.com/screenshots/rm01.png"
|
||||
description: "Screenshot URL"
|
||||
Logo:
|
||||
type: "string"
|
||||
description: "Icon associated to the extension"
|
||||
example: "fa-database"
|
||||
Price:
|
||||
type: "string"
|
||||
description: "Extension price"
|
||||
example: "US$9.95"
|
||||
PriceDescription:
|
||||
type: "string"
|
||||
description: "Details about extension pricing"
|
||||
example: "Price per instance per year"
|
||||
ShopURL:
|
||||
type: "string"
|
||||
description: "URL used to buy the extension"
|
||||
example: "https://portainer.io/checkout/?add-to-cart=1164"
|
||||
UpdateAvailable:
|
||||
type: "boolean"
|
||||
description: "Is an update available for this extension"
|
||||
example: "true"
|
||||
Version:
|
||||
type: "string"
|
||||
description: "Extension version"
|
||||
example: "1.0.0"
|
||||
License:
|
||||
$ref: "#/definitions/LicenseInformation"
|
||||
ExtensionListResponse:
|
||||
type: "array"
|
||||
items:
|
||||
$ref: "#/definitions/Extension"
|
||||
ExtensionCreateRequest:
|
||||
type: "object"
|
||||
required:
|
||||
- "License"
|
||||
properties:
|
||||
License:
|
||||
type: "string"
|
||||
example: "1-uKmVwboSWVIZv5URmE0VRkpbPX0rrCVeDxJl97LZ0piltw2SU28DSrNwPZAHCEAwB2SeKm6BCFcVwzGMBEixKQ"
|
||||
description: "License key"
|
||||
ExtensionUpdateRequest:
|
||||
type: "object"
|
||||
required:
|
||||
- "Version"
|
||||
properties:
|
||||
Version:
|
||||
type: "string"
|
||||
example: "1.1.0"
|
||||
description: "New version of the extension"
|
||||
RoleListResponse:
|
||||
type: "array"
|
||||
items:
|
||||
$ref: "#/definitions/Role"
|
||||
Role:
|
||||
type: "object"
|
||||
properties:
|
||||
Id:
|
||||
type: "integer"
|
||||
description: "Role identifier"
|
||||
example: 2
|
||||
Name:
|
||||
type: "string"
|
||||
description: "Role name"
|
||||
example: "HelpDesk"
|
||||
Description:
|
||||
type: "string"
|
||||
description: "Role description"
|
||||
example: "Read-only access of all resources in an endpoint"
|
||||
Authorizations:
|
||||
$ref: "#/definitions/Authorizations"
|
||||
Authorizations:
|
||||
type: "object"
|
||||
description: "Authorizations associated to a role"
|
||||
additionalProperties:
|
||||
type: "object"
|
||||
properties:
|
||||
authorization:
|
||||
type: "string"
|
||||
value:
|
||||
type: "boolean"
|
||||
example:
|
||||
"DockerContainerList": true
|
||||
"DockerVolumeList": true
|
||||
|
|
|
|||
Loading…
Reference in New Issue