docs/api: document /_ping?capabilities=1 endpoint

We've added a query parameter `capabilities` to the `/_ping` endpoint
that allows clients to request capabilities that the engine supports
in the `/_ping` response.

Document this change in `docs/api/version-history.md`, and update the
swagger yaml accordingly.

For Swagger, I've added a "separate" endpoint documenting the new
behavior. This has to do with Swagger not supporting different
responses for the same path (either based on query params or
content-types/other headers) – see OAI/OpenAPI-Specification#146

This is supported in OpenAPI 3.0
(OAI/OpenAPI-Specification#146 (comment)),
so we could fix this up in the future.

Signed-off-by: Laura Brehm <[email protected]>

Author: laurazard

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"

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<API-version>/<endpoint>`).
+* `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