Merge pull request #132 from thaJeztah/docs-cherry-picks
[17.06.1] Swagger and API docs cherry-picks
This commit is contained in:
Victor Vieux
GitHub
@@ -711,7 +711,7 @@ definitions:
|
||||
- "process"
|
||||
- "hyperv"
|
||||
|
||||
Config:
|
||||
ContainerConfig:
|
||||
description: "Configuration for a container that is portable between hosts"
|
||||
type: "object"
|
||||
properties:
|
||||
@@ -908,7 +908,7 @@ definitions:
|
||||
type: "string"
|
||||
x-nullable: false
|
||||
ContainerConfig:
|
||||
$ref: "#/definitions/Config"
|
||||
$ref: "#/definitions/ContainerConfig"
|
||||
DockerVersion:
|
||||
type: "string"
|
||||
x-nullable: false
|
||||
@@ -916,7 +916,7 @@ definitions:
|
||||
type: "string"
|
||||
x-nullable: false
|
||||
Config:
|
||||
$ref: "#/definitions/Config"
|
||||
$ref: "#/definitions/ContainerConfig"
|
||||
Architecture:
|
||||
type: "string"
|
||||
x-nullable: false
|
||||
@@ -1078,17 +1078,27 @@ definitions:
|
||||
type: "string"
|
||||
UsageData:
|
||||
type: "object"
|
||||
x-nullable: true
|
||||
required: [Size, RefCount]
|
||||
description: |
|
||||
Usage details about the volume. This information is used by the
|
||||
`GET /system/df` endpoint, and omitted in other endpoints.
|
||||
properties:
|
||||
Size:
|
||||
type: "integer"
|
||||
description: "The disk space used by the volume (local driver only)"
|
||||
default: -1
|
||||
description: |
|
||||
Amount of disk space used by the volume (in bytes). This information
|
||||
is only available for volumes created with the `"local"` volume
|
||||
driver. For volumes created with other volume drivers, this field
|
||||
is set to `-1` ("not available")
|
||||
x-nullable: false
|
||||
RefCount:
|
||||
type: "integer"
|
||||
default: -1
|
||||
description: "The number of containers referencing this volume."
|
||||
description: |
|
||||
The number of containers referencing this volume. This field
|
||||
is set to `-1` if the reference-count is not available.
|
||||
x-nullable: false
|
||||
|
||||
example:
|
||||
@@ -2003,6 +2013,57 @@ definitions:
|
||||
description: "A list of additional groups that the container process will run as."
|
||||
items:
|
||||
type: "string"
|
||||
Privileges:
|
||||
type: "object"
|
||||
description: "Security options for the container"
|
||||
properties:
|
||||
CredentialSpec:
|
||||
type: "object"
|
||||
description: "CredentialSpec for managed service account (Windows only)"
|
||||
properties:
|
||||
File:
|
||||
type: "string"
|
||||
description: |
|
||||
Load credential spec from this file. The file is read by the daemon, and must be present in the
|
||||
`CredentialSpecs` subdirectory in the docker data directory, which defaults to
|
||||
`C:\ProgramData\Docker\` on Windows.
|
||||
|
||||
For example, specifying `spec.json` loads `C:\ProgramData\Docker\CredentialSpecs\spec.json`.
|
||||
|
||||
<p><br /></p>
|
||||
|
||||
> **Note**: `CredentialSpec.File` and `CredentialSpec.Registry` are mutually exclusive.
|
||||
Registry:
|
||||
type: "string"
|
||||
description: |
|
||||
Load credential spec from this value in the Windows registry. The specified registry value must be
|
||||
located in:
|
||||
|
||||
`HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs`
|
||||
|
||||
<p><br /></p>
|
||||
|
||||
|
||||
> **Note**: `CredentialSpec.File` and `CredentialSpec.Registry` are mutually exclusive.
|
||||
SELinuxContext:
|
||||
type: "object"
|
||||
description: "SELinux labels of the container"
|
||||
properties:
|
||||
Disable:
|
||||
type: "boolean"
|
||||
description: "Disable SELinux"
|
||||
User:
|
||||
type: "string"
|
||||
description: "SELinux user label"
|
||||
Role:
|
||||
type: "string"
|
||||
description: "SELinux role label"
|
||||
Type:
|
||||
type: "string"
|
||||
description: "SELinux type label"
|
||||
Level:
|
||||
type: "string"
|
||||
description: "SELinux level label"
|
||||
TTY:
|
||||
description: "Whether a pseudo-TTY should be allocated."
|
||||
type: "boolean"
|
||||
@@ -2085,6 +2146,37 @@ definitions:
|
||||
SecretName is the name of the secret that this references, but this is just provided for
|
||||
lookup/display purposes. The secret in the reference will be identified by its ID.
|
||||
type: "string"
|
||||
Configs:
|
||||
description: "Configs contains references to zero or more configs that will be exposed to the service."
|
||||
type: "array"
|
||||
items:
|
||||
type: "object"
|
||||
properties:
|
||||
File:
|
||||
description: "File represents a specific target that is backed by a file."
|
||||
type: "object"
|
||||
properties:
|
||||
Name:
|
||||
description: "Name represents the final filename in the filesystem."
|
||||
type: "string"
|
||||
UID:
|
||||
description: "UID represents the file UID."
|
||||
type: "string"
|
||||
GID:
|
||||
description: "GID represents the file GID."
|
||||
type: "string"
|
||||
Mode:
|
||||
description: "Mode represents the FileMode of the file."
|
||||
type: "integer"
|
||||
format: "uint32"
|
||||
ConfigID:
|
||||
description: "ConfigID represents the ID of the specific config that we're referencing."
|
||||
type: "string"
|
||||
ConfigName:
|
||||
description: |
|
||||
ConfigName is the name of the config that this references, but this is just provided for
|
||||
lookup/display purposes. The config in the reference will be identified by its ID.
|
||||
type: "string"
|
||||
|
||||
Resources:
|
||||
description: "Resource requirements which apply to each individual container created as part of the service."
|
||||
@@ -2688,7 +2780,39 @@ definitions:
|
||||
type: "string"
|
||||
format: "dateTime"
|
||||
Spec:
|
||||
$ref: "#/definitions/ServiceSpec"
|
||||
$ref: "#/definitions/SecretSpec"
|
||||
ConfigSpec:
|
||||
type: "object"
|
||||
properties:
|
||||
Name:
|
||||
description: "User-defined name of the config."
|
||||
type: "string"
|
||||
Labels:
|
||||
description: "User-defined key/value metadata."
|
||||
type: "object"
|
||||
additionalProperties:
|
||||
type: "string"
|
||||
Data:
|
||||
description: "Base64-url-safe-encoded config data"
|
||||
type: "array"
|
||||
items:
|
||||
type: "string"
|
||||
Config:
|
||||
type: "object"
|
||||
properties:
|
||||
ID:
|
||||
type: "string"
|
||||
Version:
|
||||
$ref: "#/definitions/ObjectVersion"
|
||||
CreatedAt:
|
||||
type: "string"
|
||||
format: "dateTime"
|
||||
UpdatedAt:
|
||||
type: "string"
|
||||
format: "dateTime"
|
||||
Spec:
|
||||
$ref: "#/definitions/ConfigSpec"
|
||||
|
||||
paths:
|
||||
/containers/json:
|
||||
get:
|
||||
@@ -2893,7 +3017,7 @@ paths:
|
||||
description: "Container to create"
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: "#/definitions/Config"
|
||||
- $ref: "#/definitions/ContainerConfig"
|
||||
- type: "object"
|
||||
properties:
|
||||
HostConfig:
|
||||
@@ -3119,7 +3243,7 @@ paths:
|
||||
all processes in the container. Freezing the process requires the process to
|
||||
be running. As a result, paused containers are both `Running` _and_ `Paused`.
|
||||
|
||||
Use the `Status` field instead to determin if a container's state is "running".
|
||||
Use the `Status` field instead to determine if a container's state is "running".
|
||||
type: "boolean"
|
||||
Paused:
|
||||
description: "Whether this container is paused."
|
||||
@@ -3191,7 +3315,7 @@ paths:
|
||||
items:
|
||||
$ref: "#/definitions/MountPoint"
|
||||
Config:
|
||||
$ref: "#/definitions/Config"
|
||||
$ref: "#/definitions/ContainerConfig"
|
||||
NetworkSettings:
|
||||
$ref: "#/definitions/NetworkConfig"
|
||||
examples:
|
||||
@@ -5557,7 +5681,7 @@ paths:
|
||||
in: "body"
|
||||
description: "The container configuration"
|
||||
schema:
|
||||
$ref: "#/definitions/Config"
|
||||
$ref: "#/definitions/ContainerConfig"
|
||||
- name: "container"
|
||||
in: "query"
|
||||
description: "The ID or name of the container to commit"
|
||||
@@ -5596,16 +5720,22 @@ paths:
|
||||
|
||||
Various objects within Docker report events when something happens to them.
|
||||
|
||||
Containers report these events: `attach, commit, copy, create, destroy, detach, die, exec_create, exec_detach, exec_start, export, health_status, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update`
|
||||
Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, and `update`
|
||||
|
||||
Images report these events: `delete, import, load, pull, push, save, tag, untag`
|
||||
Images report these events: `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, and `untag`
|
||||
|
||||
Volumes report these events: `create, mount, unmount, destroy`
|
||||
Volumes report these events: `create`, `mount`, `unmount`, and `destroy`
|
||||
|
||||
Networks report these events: `create, connect, disconnect, destroy`
|
||||
Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, and `remove`
|
||||
|
||||
The Docker daemon reports these events: `reload`
|
||||
|
||||
Services report these events: `create`, `update`, and `remove`
|
||||
|
||||
Nodes report these events: `create`, `update`, and `remove`
|
||||
|
||||
Secrets report these events: `create`, `update`, and `remove`
|
||||
|
||||
operationId: "SystemEvents"
|
||||
produces:
|
||||
- "application/json"
|
||||
@@ -5679,7 +5809,8 @@ paths:
|
||||
- `label=<string>` image or container label
|
||||
- `network=<string>` network name or ID
|
||||
- `plugin`=<string> plugin name or ID
|
||||
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, or `daemon`
|
||||
- `scope`＝<string> local or swarm
|
||||
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service` or `secret`
|
||||
- `volume=<string>` volume name or ID
|
||||
type: "string"
|
||||
tags: ["System"]
|
||||
@@ -5760,13 +5891,13 @@ paths:
|
||||
-
|
||||
Name: "my-volume"
|
||||
Driver: "local"
|
||||
Mountpoint: ""
|
||||
Mountpoint: "/var/lib/docker/volumes/my-volume/_data"
|
||||
Labels: null
|
||||
Scope: ""
|
||||
Scope: "local"
|
||||
Options: null
|
||||
UsageData:
|
||||
Size: 0
|
||||
RefCount: 0
|
||||
Size: 10920104
|
||||
RefCount: 2
|
||||
500:
|
||||
description: "server error"
|
||||
schema:
|
||||
@@ -8400,6 +8531,198 @@ paths:
|
||||
format: "int64"
|
||||
required: true
|
||||
tags: ["Secret"]
|
||||
/configs:
|
||||
get:
|
||||
summary: "List configs"
|
||||
operationId: "ConfigList"
|
||||
produces:
|
||||
- "application/json"
|
||||
responses:
|
||||
200:
|
||||
description: "no error"
|
||||
schema:
|
||||
type: "array"
|
||||
items:
|
||||
$ref: "#/definitions/Config"
|
||||
example:
|
||||
- ID: "ktnbjxoalbkvbvedmg1urrz8h"
|
||||
Version:
|
||||
Index: 11
|
||||
CreatedAt: "2016-11-05T01:20:17.327670065Z"
|
||||
UpdatedAt: "2016-11-05T01:20:17.327670065Z"
|
||||
Spec:
|
||||
Name: "server.conf"
|
||||
500:
|
||||
description: "server error"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
503:
|
||||
description: "node is not part of a swarm"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
parameters:
|
||||
- name: "filters"
|
||||
in: "query"
|
||||
type: "string"
|
||||
description: |
|
||||
A JSON encoded value of the filters (a `map[string][]string`) to process on the configs list. Available filters:
|
||||
|
||||
- `id=<config id>`
|
||||
- `label=<key> or label=<key>=value`
|
||||
- `name=<config name>`
|
||||
- `names=<config name>`
|
||||
tags: ["Config"]
|
||||
/configs/create:
|
||||
post:
|
||||
summary: "Create a config"
|
||||
operationId: "ConfigCreate"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
responses:
|
||||
201:
|
||||
description: "no error"
|
||||
schema:
|
||||
type: "object"
|
||||
properties:
|
||||
ID:
|
||||
description: "The ID of the created config."
|
||||
type: "string"
|
||||
example:
|
||||
ID: "ktnbjxoalbkvbvedmg1urrz8h"
|
||||
409:
|
||||
description: "name conflicts with an existing object"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
500:
|
||||
description: "server error"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
503:
|
||||
description: "node is not part of a swarm"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
parameters:
|
||||
- name: "body"
|
||||
in: "body"
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: "#/definitions/ConfigSpec"
|
||||
- type: "object"
|
||||
example:
|
||||
Name: "server.conf"
|
||||
Labels:
|
||||
foo: "bar"
|
||||
Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg=="
|
||||
tags: ["Config"]
|
||||
/configs/{id}:
|
||||
get:
|
||||
summary: "Inspect a config"
|
||||
operationId: "ConfigInspect"
|
||||
produces:
|
||||
- "application/json"
|
||||
responses:
|
||||
200:
|
||||
description: "no error"
|
||||
schema:
|
||||
$ref: "#/definitions/Config"
|
||||
examples:
|
||||
application/json:
|
||||
ID: "ktnbjxoalbkvbvedmg1urrz8h"
|
||||
Version:
|
||||
Index: 11
|
||||
CreatedAt: "2016-11-05T01:20:17.327670065Z"
|
||||
UpdatedAt: "2016-11-05T01:20:17.327670065Z"
|
||||
Spec:
|
||||
Name: "app-dev.crt"
|
||||
404:
|
||||
description: "config not found"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
500:
|
||||
description: "server error"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
503:
|
||||
description: "node is not part of a swarm"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
required: true
|
||||
type: "string"
|
||||
description: "ID of the config"
|
||||
tags: ["Config"]
|
||||
delete:
|
||||
summary: "Delete a config"
|
||||
operationId: "ConfigDelete"
|
||||
produces:
|
||||
- "application/json"
|
||||
responses:
|
||||
204:
|
||||
description: "no error"
|
||||
404:
|
||||
description: "config not found"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
500:
|
||||
description: "server error"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
503:
|
||||
description: "node is not part of a swarm"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
required: true
|
||||
type: "string"
|
||||
description: "ID of the config"
|
||||
tags: ["Config"]
|
||||
/configs/{id}/update:
|
||||
post:
|
||||
summary: "Update a Config"
|
||||
operationId: "ConfigUpdate"
|
||||
responses:
|
||||
200:
|
||||
description: "no error"
|
||||
400:
|
||||
description: "bad parameter"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
404:
|
||||
description: "no such config"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
500:
|
||||
description: "server error"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
503:
|
||||
description: "node is not part of a swarm"
|
||||
schema:
|
||||
$ref: "#/definitions/ErrorResponse"
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
description: "The ID or name of the config"
|
||||
type: "string"
|
||||
required: true
|
||||
- name: "body"
|
||||
in: "body"
|
||||
schema:
|
||||
$ref: "#/definitions/ConfigSpec"
|
||||
description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values."
|
||||
- name: "version"
|
||||
in: "query"
|
||||
description: "The version number of the config object being updated. This is required to avoid conflicting writes."
|
||||
type: "integer"
|
||||
format: "int64"
|
||||
required: true
|
||||
tags: ["Config"]
|
||||
/distribution/{name}/json:
|
||||
get:
|
||||
summary: "Get image information from the registry"
|
||||
|
||||
@@ -44,15 +44,23 @@ type Volume struct {
|
||||
UsageData *VolumeUsageData `json:"UsageData,omitempty"`
|
||||
}
|
||||
|
||||
// VolumeUsageData volume usage data
|
||||
// VolumeUsageData Usage details about the volume. This information is used by the
|
||||
// `GET /system/df` endpoint, and omitted in other endpoints.
|
||||
//
|
||||
// swagger:model VolumeUsageData
|
||||
type VolumeUsageData struct {
|
||||
|
||||
// The number of containers referencing this volume.
|
||||
// The number of containers referencing this volume. This field
|
||||
// is set to `-1` if the reference-count is not available.
|
||||
//
|
||||
// Required: true
|
||||
RefCount int64 `json:"RefCount"`
|
||||
|
||||
// The disk space used by the volume (local driver only)
|
||||
// Amount of disk space used by the volume (in bytes). This information
|
||||
// is only available for volumes created with the `"local"` volume
|
||||
// driver. For volumes created with other volume drivers, this field
|
||||
// is set to `-1` ("not available")
|
||||
//
|
||||
// Required: true
|
||||
Size int64 `json:"Size"`
|
||||
}
|
||||
|
||||
@@ -31,6 +31,9 @@ keywords: "API, Docker, rcli, REST, documentation"
|
||||
* `POST /containers/(name)/wait` now accepts a `condition` query parameter to indicate which state change condition to wait for. Also, response headers are now returned immediately to acknowledge that the server has registered a wait callback for the client.
|
||||
* `POST /swarm/init` now accepts a `DataPathAddr` property to set the IP-address or network interface to use for data traffic
|
||||
* `POST /swarm/join` now accepts a `DataPathAddr` property to set the IP-address or network interface to use for data traffic
|
||||
* `GET /events` now supports service, node and secret events which are emmited when users create, update and remove service, node and secret
|
||||
* `GET /events` now supports network remove event which is emmitted when users remove a swarm scoped network
|
||||
* `GET /events` now supports a filter type `scope` in which supported value could be swarm and local
|
||||
|
||||
## v1.29 API changes
|
||||
|
||||
@@ -43,6 +46,8 @@ keywords: "API, Docker, rcli, REST, documentation"
|
||||
* `POST /containers/create`, `POST /service/create` and `POST /services/(id or name)/update` now takes the field `StartPeriod` as a part of the `HealthConfig` allowing for specification of a period during which the container should not be considered unhealthy even if health checks do not pass.
|
||||
* `GET /services/(id)` now accepts an `insertDefaults` query-parameter to merge default values into the service inspect output.
|
||||
* `POST /containers/prune`, `POST /images/prune`, `POST /volumes/prune`, and `POST /networks/prune` now support a `label` filter to filter containers, images, volumes, or networks based on the label. The format of the label filter could be `label=<key>`/`label=<key>=<value>` to remove those with the specified labels, or `label!=<key>`/`label!=<key>=<value>` to remove those without the specified labels.
|
||||
* `POST /services/create` now accepts `Privileges` as part of `ContainerSpec`. Privileges currently include
|
||||
`CredentialSpec` and `SELinuxContext`.
|
||||
|
||||
## v1.28 API changes
|
||||
|
||||
|
||||
Reference in New Issue
Block a user