From 67de71a18fa8f42cf58128a3da13e96db0795d0e Mon Sep 17 00:00:00 2001 From: Anthony Lapenna Date: Tue, 11 Jun 2019 10:34:54 +1200 Subject: [PATCH] docs(api): update swagger documentation --- api/swagger.yaml | 352 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 352 insertions(+) diff --git a/api/swagger.yaml b/api/swagger.yaml index 45df32348..4cb697566 100644 --- a/api/swagger.yaml +++ b/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