beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Improve tags in swagger.yaml

Browse source 
- Consistent naming (plural, etc)
- Add section descriptions
- Add docs in swagger.yaml about how to maintain them

Signed-off-by: Ben Firshman <ben@firshman.co.uk>
This commit is contained in:
Ben Firshman 2016-11-25 11:32:13 +00:00
parent be52738a2c
commit 2aea9ad56b
No known key found for this signature in database
GPG key ID: 18296449E36D2F1E
1 changed files with 133 additions and 171 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

304
api/swagger.yaml
View file

@ -88,6 +88,48 @@ info:
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be plural, not singular.
# - There should not be too many tags, or the menu becomes unwieldly. For
# example, it is preferable to add a path to the "System" tag instead of
# creating a tag with a single path in it.
# - The order of tags in this list defines the order in the menu.
tags:
# Primary objects
- name: "Containers"
description: |
Create and manage containers.
- name: "Images"
- name: "Networks"
description: |
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.
To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.
- name: "Secrets"
# Swarm things
- name: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Tasks"
description: |
A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugins"
- name: "System"
definitions:
Port:
type: "object"
@ -2577,8 +2619,7 @@ paths:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Container"
tags: ["Containers"]
/containers/create:
post:
summary: "Create a container"
@ -2777,8 +2818,7 @@ paths:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/json:
get:
summary: "Inspect a container"
@ -3054,8 +3094,7 @@ paths:
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
@ -3131,8 +3170,7 @@ paths:
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/logs:
get:
summary: "Get container logs"
@ -3201,8 +3239,7 @@ paths:
description: "Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines."
type: "string"
default: "all"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/changes:
get:
summary: "Get changes on a container’s filesystem"
@ -3258,8 +3295,7 @@ paths:
required: true
description: "ID or name of the container"
type: "string"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/export:
get:
summary: "Export a container"
@ -3287,8 +3323,7 @@ paths:
required: true
description: "ID or name of the container"
type: "string"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
@ -3416,8 +3451,7 @@ paths:
description: "Stream the output. If false, the stats will be output once and then it will disconnect."
type: "boolean"
default: true
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/resize:
post:
summary: "Resize a container TTY"
@ -3455,8 +3489,7 @@ paths:
in: "query"
description: "Width of the tty session in characters"
type: "integer"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/start:
post:
summary: "Start a container"
@ -3489,8 +3522,7 @@ paths:
in: "query"
description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`."
type: "string"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/stop:
post:
summary: "Stop a container"
@ -3523,8 +3555,7 @@ paths:
in: "query"
description: "Number of seconds to wait before killing the container"
type: "integer"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/restart:
post:
summary: "Restart a container"
@ -3553,8 +3584,7 @@ paths:
in: "query"
description: "Number of seconds to wait before killing the container"
type: "integer"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/kill:
post:
summary: "Kill a container"
@ -3585,8 +3615,7 @@ paths:
description: "Signal to send to the container as an integer or string (e.g. `SIGINT`)"
type: "string"
default: "SIGKILL"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/update:
post:
summary: "Update a container"
@ -3647,8 +3676,7 @@ paths:
RestartPolicy:
MaximumRetryCount: 4
Name: "on-failure"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/rename:
post:
summary: "Rename a container"
@ -3682,8 +3710,7 @@ paths:
required: true
description: "New name for the container"
type: "string"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/pause:
post:
summary: "Pause a container"
@ -3712,8 +3739,7 @@ paths:
required: true
description: "ID or name of the container"
type: "string"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/unpause:
post:
summary: "Unpause a container"
@ -3739,8 +3765,7 @@ paths:
required: true
description: "ID or name of the container"
type: "string"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
@ -3884,8 +3909,7 @@ paths:
description: "Attach to `stderr`"
type: "boolean"
default: false
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/attach/ws:
get:
summary: "Attach to a container via a websocket"
@ -3945,8 +3969,7 @@ paths:
description: "Attach to `stderr`"
type: "boolean"
default: false
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/wait:
post:
summary: "Wait for a container"
@ -3981,8 +4004,7 @@ paths:
required: true
description: "ID or name of the container"
type: "string"
tags:
- "Container"
tags: ["Containers"]
/containers/{id}:
delete:
summary: "Remove a container"
@ -4021,8 +4043,7 @@ paths:
description: "If the container is running, kill it before removing it."
type: "boolean"
default: false
tags:
- "Container"
tags: ["Containers"]
/containers/{id}/archive:
head:
summary: "Get information about files in a container"
@ -4068,8 +4089,7 @@ paths:
required: true
description: "Resource in the container’s filesystem to archive."
type: "string"
tags:
- "Container"
tags: ["Containers"]
get:
summary: "Get an archive of a filesystem resource in a container"
description: "Get an tar archive of a resource in the filesystem of container id."
@ -4112,8 +4132,7 @@ paths:
required: true
description: "Resource in the container’s filesystem to archive."
type: "string"
tags:
- "Container"
tags: ["Containers"]
put:
summary: "Extract an archive of files or folders to a directory in a container"
description: "Upload a tar archive to be extracted to a path in the filesystem of container id."
@ -4164,8 +4183,7 @@ paths:
description: "The input stream must be a tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz."
schema:
type: "string"
tags:
- "Container"
tags: ["Containers"]
/containers/prune:
post:
summary: "Delete stopped containers"
@ -4193,8 +4211,7 @@ paths:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Container"
tags: ["Containers"]
/images/json:
get:
summary: "List Images"
@ -4265,8 +4282,7 @@ paths:
description: "Show digest information as a `RepoDigests` field on each image."
type: "boolean"
default: false
tags:
- "Image"
tags: ["Images"]
/build:
post:
summary: "Build an image"
@ -4413,8 +4429,7 @@ paths:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Image"
tags: ["Images"]
/images/create:
post:
summary: "Create an image"
@ -4459,8 +4474,7 @@ paths:
in: "header"
description: "A base64-encoded auth configuration. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags:
- "Image"
tags: ["Images"]
/images/{name}/json:
get:
summary: "Inspect an image"
@ -4566,8 +4580,7 @@ paths:
description: "Image name or id"
type: "string"
required: true
tags:
- "Image"
tags: ["Images"]
/images/{name}/history:
get:
summary: "Get the history of an image"
@ -4637,8 +4650,7 @@ paths:
description: "Image name or ID"
type: "string"
required: true
tags:
- "Image"
tags: ["Images"]
/images/{name}/push:
post:
summary: "Push an image"
@ -4677,8 +4689,7 @@ paths:
description: "A base64-encoded auth configuration. [See the authentication section for details.](#section/Authentication)"
type: "string"
required: true
tags:
- "Image"
tags: ["Images"]
/images/{name}/tag:
post:
summary: "Tag an image"
@ -4717,8 +4728,7 @@ paths:
in: "query"
description: "The name of the new tag."
type: "string"
tags:
- "Image"
tags: ["Images"]
/images/{name}:
delete:
summary: "Remove an image"
@ -4769,8 +4779,7 @@ paths:
description: "Do not delete untagged parent images"
type: "boolean"
default: false
tags:
- "Image"
tags: ["Images"]
/images/search:
get:
summary: "Search images"
@ -4836,8 +4845,7 @@ paths:
- `is-automated=(true|false)`
- `is-official=(true|false)`
type: "string"
tags:
- "Image"
tags: ["Images"]
/images/prune:
post:
summary: "Delete unused images"
@ -4875,8 +4883,7 @@ paths:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Image"
tags: ["Images"]
/auth:
post:
summary: "Check auth configuration"
@ -4915,7 +4922,7 @@ paths:
description: "Authentication to check"
schema:
$ref: "#/definitions/AuthConfig"
tags: ["Registry"]
tags: ["System"]
/info:
get:
summary: "Get system information"
@ -5127,8 +5134,7 @@ paths:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Misc"
tags: ["System"]
/version:
get:
summary: "Get version"
@ -5178,8 +5184,7 @@ paths:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Misc"
tags: ["System"]
/_ping:
get:
summary: "Ping"
@ -5197,8 +5202,7 @@ paths:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Misc"
tags: ["System"]
/commit:
post:
summary: "Create a new image from a container"
@ -5258,8 +5262,7 @@ paths:
in: "query"
description: "`Dockerfile` instructions to apply while committing"
type: "string"
tags:
- "Image"
tags: ["Images"]
/events:
get:
summary: "Monitor events"
@ -5349,8 +5352,7 @@ paths:
- `network=<string>` network name or ID
- `daemon=<string>` daemon name or ID
type: "string"
tags:
- "Misc"
tags: ["System"]
/system/df:
get:
summary: "Get data usage information"
@ -5438,8 +5440,7 @@ paths:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Misc"
tags: ["System"]
/images/{name}/get:
get:
summary: "Export an image"
@ -5486,8 +5487,7 @@ paths:
description: "Image name or ID"
type: "string"
required: true
tags:
- "Image"
tags: ["Images"]
/images/get:
get:
summary: "Export several images"
@ -5517,8 +5517,7 @@ paths:
type: "array"
items:
type: "string"
tags:
- "Image"
tags: ["Images"]
/images/load:
post:
summary: "Import images"
@ -5550,8 +5549,7 @@ paths:
description: "Suppress progress details during load."
type: "boolean"
default: false
tags:
- "Image"
tags: ["Images"]
/containers/{id}/exec:
post:
summary: "Create an exec instance"
@ -5637,8 +5635,7 @@ paths:
description: "ID or name of container"
type: "string"
required: true
tags:
- "Exec"
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
@ -5679,8 +5676,7 @@ paths:
description: "Exec instance ID"
required: true
type: "string"
tags:
- "Exec"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
@ -5707,8 +5703,7 @@ paths:
in: "query"
description: "Width of the TTY session in characters"
type: "integer"
tags:
- "Exec"
tags: ["Exec"]
/exec/{id}/json:
get:
summary: "Inspect an exec instance"
@ -5775,8 +5770,7 @@ paths:
description: "Exec instance ID"
required: true
type: "string"
tags:
- "Exec"
tags: ["Exec"]
/volumes:
get:
@ -5838,7 +5832,7 @@ paths:
driver name.
type: "string"
format: "json"
tags: ["Volume"]
tags: ["Volumes"]
/volumes/create:
post:
@ -5888,7 +5882,7 @@ paths:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Driver: "custom"
tags: ["Volume"]
tags: ["Volumes"]
/volumes/{name}:
get:
@ -5914,7 +5908,7 @@ paths:
required: true
description: "Volume name or ID"
type: "string"
tags: ["Volume"]
tags: ["Volumes"]
delete:
summary: "Remove a volume"
@ -5946,7 +5940,7 @@ paths:
description: "Force the removal of the volume"
type: "boolean"
default: false
tags: ["Volume"]
tags: ["Volumes"]
/volumes/prune:
post:
summary: "Delete unused volumes"
@ -5974,8 +5968,7 @@ paths:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Volume"
tags: ["Volumes"]
/networks:
get:
summary: "List networks"
@ -6056,7 +6049,7 @@ paths:
- `name=<network-name>` Matches all or part of a network name.
- `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks.
type: "string"
tags: ["Network"]
tags: ["Networks"]
/networks/{id}:
get:
@ -6079,7 +6072,7 @@ paths:
description: "Network ID or name"
required: true
type: "string"
tags: ["Network"]
tags: ["Networks"]
delete:
summary: "Remove a network"
@ -6101,7 +6094,7 @@ paths:
description: "Network ID or name"
required: true
type: "string"
tags: ["Network"]
tags: ["Networks"]
/networks/create:
post:
@ -6197,7 +6190,7 @@ paths:
Labels:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
tags: ["Network"]
tags: ["Networks"]
/networks/{id}/connect:
post:
@ -6243,7 +6236,7 @@ paths:
IPAMConfig:
IPv4Address: "172.24.56.89"
IPv6Address: "2001:db8::5689"
tags: ["Network"]
tags: ["Networks"]
/networks/{id}/disconnect:
post:
@ -6284,7 +6277,7 @@ paths:
Force:
type: "boolean"
description: "Force the container to disconnect from the network."
tags: ["Network"]
tags: ["Networks"]
/networks/prune:
post:
summary: "Delete unused networks"
@ -6308,8 +6301,7 @@ paths:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Network"
tags: ["Networks"]
/plugins:
get:
summary: "List plugins"
@ -6459,8 +6451,7 @@ paths:
in: "header"
description: "A base64-encoded auth configuration to use when pulling a plugin from a registry. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags:
- "Plugins"
tags: ["Plugins"]
/plugins/{name}:
get:
summary: "Inspect a plugin"
@ -6484,8 +6475,7 @@ paths:
description: "The name of the plugin. The `:latest` tag is optional, and is the default if omitted."
required: true
type: "string"
tags:
- "Plugins"
tags: ["Plugins"]
delete:
summary: "Remove a plugin"
operationId: "DeletePlugins"
@ -6513,8 +6503,7 @@ paths:
description: "Disable the plugin before removing. This may result in issues if the plugin is in use by a container."
type: "boolean"
default: false
tags:
- "Plugins"
tags: ["Plugins"]
/plugins/{name}/enable:
post:
summary: "Enable a plugin"
@ -6537,8 +6526,7 @@ paths:
description: "Set the HTTP client timeout (in seconds)"
type: "integer"
default: 0
tags:
- "Plugins"
tags: ["Plugins"]
/plugins/{name}/disable:
post:
summary: "Disable a plugin"
@ -6556,8 +6544,7 @@ paths:
description: "The name of the plugin. The `:latest` tag is optional, and is the default if omitted."
required: true
type: "string"
tags:
- "Plugins"
tags: ["Plugins"]
/plugins/create:
post:
summary: "Create a plugin"
@ -6583,8 +6570,7 @@ paths:
schema:
type: "string"
format: "binary"
tags:
- "Plugins"
tags: ["Plugins"]
/plugins/{name}/push:
post:
summary: "Push a plugin"
@ -6608,8 +6594,7 @@ paths:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Plugins"
tags: ["Plugins"]
/plugins/{name}/set:
post:
summary: "Configure a plugin"
@ -6640,8 +6625,7 @@ paths:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Plugins"
tags: ["Plugins"]
/nodes:
get:
summary: "List nodes"
@ -6670,8 +6654,7 @@ paths:
- `name=<node name>`
- `role=`(`manager`|`worker`)`
type: "string"
tags:
- "Nodes"
tags: ["Nodes"]
/nodes/{id}:
get:
summary: "Inspect a node"
@ -6695,8 +6678,7 @@ paths:
description: "The ID or name of the node"
type: "string"
required: true
tags:
- "Nodes"
tags: ["Nodes"]
delete:
summary: "Delete a node"
operationId: "DeleteNodes"
@ -6722,8 +6704,7 @@ paths:
description: "Force remove a node from the swarm"
default: false
type: "boolean"
tags:
- "Nodes"
tags: ["Nodes"]
/nodes/{id}/update:
post:
summary: "Update a node"
@ -6755,8 +6736,7 @@ paths:
type: "integer"
format: "int64"
required: true
tags:
- "Nodes"
tags: ["Nodes"]
/swarm:
get:
summary: "Inspect swarm"
@ -6808,8 +6788,7 @@ paths:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Swarm"
tags: ["Swarm"]
/swarm/init:
post:
summary: "Initialize a new swarm"
@ -6865,8 +6844,7 @@ paths:
CAConfig: {}
EncryptionConfig:
AutoLockManagers: false
tags:
- "Swarm"
tags: ["Swarm"]
/swarm/join:
post:
summary: "Join an existing swarm"
@ -6911,8 +6889,7 @@ paths:
RemoteAddrs:
- "node1:2377"
JoinToken: "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
tags:
- "Swarm"
tags: ["Swarm"]
/swarm/leave:
post:
summary: "Leave a swarm"
@ -6934,8 +6911,7 @@ paths:
in: "query"
type: "boolean"
default: false
tags:
- "Swarm"
tags: ["Swarm"]
/swarm/update:
post:
summary: "Update a swarm"
@ -6982,8 +6958,7 @@ paths:
description: "Rotate the manager unlock key."
type: "boolean"
default: false
tags:
- "Swarm"
tags: ["Swarm"]
/swarm/unlockkey:
get:
summary: "Get the unlock key"
@ -7005,8 +6980,7 @@ paths:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Swarm"
tags: ["Swarm"]
/swarm/unlock:
post:
summary: "Unlock a locked manager"
@ -7034,8 +7008,7 @@ paths:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags:
- "Swarm"
tags: ["Swarm"]
/services:
get:
summary: "List services"
@ -7061,8 +7034,7 @@ paths:
- `id=<service id>`
- `name=<service name>`
- `label=<service label>`
tags:
- "Services"
tags: ["Services"]
/services/create:
post:
summary: "Create a service"
@ -7159,8 +7131,7 @@ paths:
in: "header"
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags:
- "Services"
tags: ["Services"]
/services/{id}:
get:
summary: "Inspect a service"
@ -7184,8 +7155,7 @@ paths:
description: "ID or name of service."
required: true
type: "string"
tags:
- "Services"
tags: ["Services"]
delete:
summary: "Delete a service"
operationId: "DeleteServices"
@ -7206,8 +7176,7 @@ paths:
description: "ID or name of service."
required: true
type: "string"
tags:
- "Services"
tags: ["Services"]
/services/{id}/update:
post:
summary: "Update a service"
@ -7359,8 +7328,7 @@ paths:
description: "Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines."
type: "string"
default: "all"
tags:
- "Services"
tags: ["Services"]
/tasks:
get:
summary: "List tasks"
@ -7503,8 +7471,7 @@ paths:
- `node=<node id or name>`
- `label=key` or `label="key=value"`
- `desired-state=(running | shutdown | accepted)`
tags:
- "Tasks"
tags: ["Tasks"]
/tasks/{id}:
get:
summary: "Inspect a task"
@ -7530,8 +7497,7 @@ paths:
description: "ID of the task"
required: true
type: "string"
tags:
- "Tasks"
tags: ["Tasks"]
/secrets:
get:
summary: "List secrets"
@ -7565,8 +7531,7 @@ paths:
A JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list. Available filters:
- `names=<secret name>`
tags:
- "Secrets"
tags: ["Secrets"]
/secrets/create:
post:
summary: "Create a secret"
@ -7610,8 +7575,7 @@ paths:
Labels:
foo: "bar"
Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg=="
tags:
- "Secrets"
tags: ["Secrets"]
/secrets/{id}:
get:
summary: "Inspect a secret"
@ -7649,8 +7613,7 @@ paths:
required: true
type: "string"
description: "ID of the secret"
tags:
- "Secrets"
tags: ["Secrets"]
delete:
summary: "Delete a secret"
operationId: "SecretsDelete"
@ -7673,5 +7636,4 @@ paths:
required: true
type: "string"
description: "ID of the secret"
tags:
- "Secrets"
tags: ["Secrets"]