From 2aea9ad56b7dc59858abe15b2ae9f60ede294b2f Mon Sep 17 00:00:00 2001 From: Ben Firshman Date: Fri, 25 Nov 2016 11:32:13 +0000 Subject: [PATCH] Improve tags in swagger.yaml - Consistent naming (plural, etc) - Add section descriptions - Add docs in swagger.yaml about how to maintain them Signed-off-by: Ben Firshman --- api/swagger.yaml | 304 +++++++++++++++++++++-------------------------- 1 file changed, 133 insertions(+), 171 deletions(-) diff --git a/api/swagger.yaml b/api/swagger.yaml index 8852641e99..8244c8b0c2 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -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-` where `` 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=` network name or ID - `daemon=` 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=` 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=` - `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=` - `name=` - `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=` - `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=` - 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"]