docs/api: document /_ping?capabilities=v1 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,17 @@ tags:
     x-displayName: "System"
 
 definitions:
+  Capabilities:
+    description: "Represents engine capabilities"
+    type: "object"
+    required: ["registry-client-auth"]
+    properties:
+      registry-client-auth:
+        description: "Whether the engine supports client auth handling."
+        type: "boolean"
+        x-nullable: false
+    example:
+      registry-client-auth: true
   Port:
     type: "object"
     description: "An open port on a container"
@@ -9709,6 +9720,83 @@ paths:
           schema:
             $ref: "#/definitions/ErrorResponse"
       tags: ["System"]
+  # Using a zero-width character here to define a separate /_ping endpoint to describe the
+  # /_ping?features=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: |
+            TODO
+          # marked as required since this is a separate endpoint in the swagger yaml.
+          required: true
+          type: "string"
+          enum: ["v1"]
+      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

@@ -58,6 +58,10 @@ keywords: "API, Docker, rcli, REST, documentation"
   the one that sorts first is picked.
 * `GET /containers/json` now returns a `GwPriority` field in `NetworkSettings`
   for each network endpoint.
+* `GET` `/_ping` endpoint now supports a `capabilities` query parameter (currently only
+  takes a constant `v1`, e.g. `GET /_ping?capabilities=v1`). If set, instead of the
+  response body containing `OK`, the daemon responds with with a json representation
+  of the engine's capabilites (`system.Capabilities`).
 
 ## v1.47 API changes