diff --git a/api/swagger.yaml b/api/swagger.yaml index b9f805a52f73d..b234030ce7359 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -173,6 +173,20 @@ tags: x-displayName: "System" definitions: + Capabilities: + description: "Represents engine capabilities" + type: "object" + properties: + v_: + description: "The version of capabilities this response represents." + type: integer + x-nullable: false + registry-client-auth: + description: "Whether the engine supports client auth handling." + type: "boolean" + x-nullable: true + example: + registry-client-auth: true Port: type: "object" description: "An open port on a container" @@ -9709,6 +9723,82 @@ paths: schema: $ref: "#/definitions/ErrorResponse" tags: ["System"] + # Using a zero-width character here to define a separate /_ping endpoint to describe the + # /_ping?capabilities=v1 API since otherwise Swagger won't allow us to define multiple + # responses for the same endpoint depending on query parameter. + # This is however supported by OpenAPI v3. + # See: https://github.com/OAI/OpenAPI-Specification/issues/146 + # and https://github.com/OAI/OpenAPI-Specification/issues/182 + /_ping​: + get: + summary: "/_ping?capabilities=v1" + description: | + This is the same endpoint as `GET /_ping`, but describes the different + response when it is called with the `capabilities=v1` query parameter. + + In this case, the daemon instead responds with a `Content-Type` of + `application/json` and writes a json represenation of the engine's + capabilities in the response body. + operationId: "SystemPingCapabilities" + produces: ["application/json"] + parameters: + - name: "capabilities" + in: "query" + description: The capabilities API version being requested. + # marked as required since this is a separate endpoint in the swagger yaml. + required: true + type: "string" + enum: ["1"] + responses: + 200: + description: "no error" + schema: + $ref: "#/definitions/Capabilities" + headers: + Api-Version: + type: "string" + description: "Max API Version the server supports" + Builder-Version: + type: "string" + description: | + Default version of docker image builder + + The default on Linux is version "2" (BuildKit), but the daemon + can be configured to recommend version "1" (classic Builder). + Windows does not yet support BuildKit for native Windows images, + and uses "1" (classic builder) as a default. + + This value is a recommendation as advertised by the daemon, and + it is up to the client to choose which builder to use. + default: "2" + Docker-Experimental: + type: "boolean" + description: "If the server is running with experimental mode enabled" + Swarm: + type: "string" + enum: ["inactive", "pending", "error", "locked", "active/worker", "active/manager"] + description: | + Contains information about Swarm status of the daemon, + and if the daemon is acting as a manager or worker node. + default: "inactive" + Cache-Control: + type: "string" + default: "no-cache, no-store, must-revalidate" + Pragma: + type: "string" + default: "no-cache" + 500: + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + headers: + Cache-Control: + type: "string" + default: "no-cache, no-store, must-revalidate" + Pragma: + type: "string" + default: "no-cache" + tags: ["System"] /commit: post: summary: "Create a new image from a container" diff --git a/docs/api/version-history.md b/docs/api/version-history.md index 52f80ee973809..99a8f23ec5e6d 100644 --- a/docs/api/version-history.md +++ b/docs/api/version-history.md @@ -62,6 +62,10 @@ keywords: "API, Docker, rcli, REST, documentation" `GET /debug/pprof/profile`, `GET /debug/pprof/symbol`, `GET /debug/pprof/trace`, `GET /debug/pprof/{name}`) are now also accessible through the versioned-API paths (`/v/`). +* `GET` `/_ping` endpoint now optionally supports a `capabilities` query parameter + (e.g. `GET /_ping?capabilities=1`). If set, instead of the response body containing + `OK`, the daemon responds with a JSON Content-Type instead of `text/plain`, and + includes the engine capabilities in the response. ## v1.47 API changes