[20.10 backport] assorted swagger updates in documentation

docs/api/v1.30.yaml

@@ -757,7 +757,15 @@ definitions:
               - "hyperv"
 
   ContainerConfig:
-    description: "Configuration for a container that is portable between hosts"
+    description: |
+      Configuration for a container that is portable between hosts.
+
+      When used as `ContainerConfig` field in an image, `ContainerConfig` is an
+      optional field containing the configuration of the container that was last
+      committed when creating the image.
+
+      Previous versions of Docker builder used this field to store build cache,
+      and it is not in active use anymore.
     type: "object"
     properties:
       Hostname:

docs/api/v1.31.yaml

@@ -758,7 +758,15 @@ definitions:
               - "hyperv"
 
   ContainerConfig:
-    description: "Configuration for a container that is portable between hosts"
+    description: |
+      Configuration for a container that is portable between hosts.
+
+      When used as `ContainerConfig` field in an image, `ContainerConfig` is an
+      optional field containing the configuration of the container that was last
+      committed when creating the image.
+
+      Previous versions of Docker builder used this field to store build cache,
+      and it is not in active use anymore.
     type: "object"
     properties:
       Hostname:

docs/api/v1.32.yaml

@@ -821,7 +821,15 @@ definitions:
               - "hyperv"
 
   ContainerConfig:
-    description: "Configuration for a container that is portable between hosts"
+    description: |
+      Configuration for a container that is portable between hosts.
+
+      When used as `ContainerConfig` field in an image, `ContainerConfig` is an
+      optional field containing the configuration of the container that was last
+      committed when creating the image.
+
+      Previous versions of Docker builder used this field to store build cache,
+      and it is not in active use anymore.
     type: "object"
     properties:
       Hostname:

docs/api/v1.33.yaml

@@ -826,7 +826,15 @@ definitions:
               - "hyperv"
 
   ContainerConfig:
-    description: "Configuration for a container that is portable between hosts"
+    description: |
+      Configuration for a container that is portable between hosts.
+
+      When used as `ContainerConfig` field in an image, `ContainerConfig` is an
+      optional field containing the configuration of the container that was last
+      committed when creating the image.
+
+      Previous versions of Docker builder used this field to store build cache,
+      and it is not in active use anymore.
     type: "object"
     properties:
       Hostname:

docs/api/v1.34.yaml

@@ -837,7 +837,15 @@ definitions:
               - "hyperv"
 
   ContainerConfig:
-    description: "Configuration for a container that is portable between hosts"
+    description: |
+      Configuration for a container that is portable between hosts.
+
+      When used as `ContainerConfig` field in an image, `ContainerConfig` is an
+      optional field containing the configuration of the container that was last
+      committed when creating the image.
+
+      Previous versions of Docker builder used this field to store build cache,
+      and it is not in active use anymore.
     type: "object"
     properties:
       Hostname:

docs/api/v1.35.yaml

@@ -817,7 +817,15 @@ definitions:
               - "hyperv"
 
   ContainerConfig:
-    description: "Configuration for a container that is portable between hosts"
+    description: |
+      Configuration for a container that is portable between hosts.
+
+      When used as `ContainerConfig` field in an image, `ContainerConfig` is an
+      optional field containing the configuration of the container that was last
+      committed when creating the image.
+
+      Previous versions of Docker builder used this field to store build cache,
+      and it is not in active use anymore.
     type: "object"
     properties:
       Hostname:

docs/api/v1.36.yaml

@@ -817,7 +817,15 @@ definitions:
               - "hyperv"
 
   ContainerConfig:
-    description: "Configuration for a container that is portable between hosts"
+    description: |
+      Configuration for a container that is portable between hosts.
+
+      When used as `ContainerConfig` field in an image, `ContainerConfig` is an
+      optional field containing the configuration of the container that was last
+      committed when creating the image.
+
+      Previous versions of Docker builder used this field to store build cache,
+      and it is not in active use anymore.
     type: "object"
     properties:
       Hostname:

docs/api/v1.37.yaml

@@ -821,7 +821,15 @@ definitions:
               - "hyperv"
 
   ContainerConfig:
-    description: "Configuration for a container that is portable between hosts"
+    description: |
+      Configuration for a container that is portable between hosts.
+
+      When used as `ContainerConfig` field in an image, `ContainerConfig` is an
+      optional field containing the configuration of the container that was last
+      committed when creating the image.
+
+      Previous versions of Docker builder used this field to store build cache,
+      and it is not in active use anymore.
     type: "object"
     properties:
       Hostname:

docs/api/v1.38.yaml

@@ -832,7 +832,15 @@ definitions:
               type: "string"
 
   ContainerConfig:
-    description: "Configuration for a container that is portable between hosts"
+    description: |
+      Configuration for a container that is portable between hosts.
+
+      When used as `ContainerConfig` field in an image, `ContainerConfig` is an
+      optional field containing the configuration of the container that was last
+      committed when creating the image.
+
+      Previous versions of Docker builder used this field to store build cache,
+      and it is not in active use anymore.
     type: "object"
     properties:
       Hostname:

docs/api/v1.39.yaml

@@ -1067,6 +1067,13 @@ definitions:
   ContainerConfig:
     description: |
       Configuration for a container that is portable between hosts.
+
+      When used as `ContainerConfig` field in an image, `ContainerConfig` is an
+      optional field containing the configuration of the container that was last
+      committed when creating the image.
+
+      Previous versions of Docker builder used this field to store build cache,
+      and it is not in active use anymore.
     type: "object"
     properties:
       Hostname:
@@ -1513,7 +1520,7 @@ definitions:
         description: |
           ID is the content-addressable ID of an image.
 
-          This identified is a content-addressable digest calculated from the
+          This identifier is a content-addressable digest calculated from the
           image's configuration (which includes the digests of layers used by
           the image).
 
@@ -1701,41 +1708,119 @@ definitions:
       - Containers
     properties:
       Id:
+        description: |
+          ID is the content-addressable ID of an image.
+
+          This identifier is a content-addressable digest calculated from the
+          image's configuration (which includes the digests of layers used by
+          the image).
+
+          Note that this digest differs from the `RepoDigests` below, which
+          holds digests of image manifests that reference the image.
         type: "string"
         x-nullable: false
+        example: "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710"
       ParentId:
+        description: |
+          ID of the parent image.
+
+          Depending on how the image was created, this field may be empty and
+          is only set for images that were built/created locally. This field
+          is empty if the image was pulled from an image registry.
         type: "string"
         x-nullable: false
+        example: ""
       RepoTags:
+        description: |
+          List of image names/tags in the local image cache that reference this
+          image.
+
+          Multiple image tags can refer to the same imagem and this list may be
+          empty if no tags reference the image, in which case the image is
+          "untagged", in which case it can still be referenced by its ID.
         type: "array"
         x-nullable: false
         items:
           type: "string"
+        example:
+          - "example:1.0"
+          - "example:latest"
+          - "example:stable"
+          - "internal.registry.example.com:5000/example:1.0"
       RepoDigests:
+        description: |
+          List of content-addressable digests of locally available image manifests
+          that the image is referenced from. Multiple manifests can refer to the
+          same image.
+
+          These digests are usually only available if the image was either pulled
+          from a registry, or if the image was pushed to a registry, which is when
+          the manifest is generated and its digest calculated.
         type: "array"
         x-nullable: false
         items:
           type: "string"
+        example:
+          - "example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb"
+          - "internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
       Created:
+        description: |
+          Date and time at which the image was created as a Unix timestamp
+          (number of seconds sinds EPOCH).
         type: "integer"
         x-nullable: false
+        example: "1644009612"
       Size:
+        description: |
+          Total size of the image including all layers it is composed of.
         type: "integer"
+        format: "int64"
         x-nullable: false
+        example: 172064416
       SharedSize:
+        description: |
+          Total size of image layers that are shared between this image and other
+          images.
+
+          This size is not calculated by default. `-1` indicates that the value
+          has not been set / calculated.
         type: "integer"
         x-nullable: false
+        example: 1239828
       VirtualSize:
+        description: |
+          Total size of the image including all layers it is composed of.
+
+          In versions of Docker before v1.10, this field was calculated from
+          the image itself and all of its parent images. Docker v1.10 and up
+          store images self-contained, and no longer use a parent-chain, making
+          this field an equivalent of the Size field.
+
+          This field is kept for backward compatibility, but may be removed in
+          a future version of the API.
         type: "integer"
+        format: "int64"
         x-nullable: false
+        example: 172064416
       Labels:
+        description: "User-defined key/value metadata."
         type: "object"
         x-nullable: false
         additionalProperties:
           type: "string"
+        example:
+          com.example.some-label: "some-value"
+          com.example.some-other-label: "some-other-value"
       Containers:
+        description: |
+          Number of containers using this image. Includes both stopped and running
+          containers.
+
+          This size is not calculated by default, and depends on which API endpoint
+          is used. `-1` indicates that the value has not been set / calculated.
         x-nullable: false
         type: "integer"
+        example: 2
 
   AuthConfig:
     type: "object"
@@ -4262,7 +4347,7 @@ definitions:
     type: "object"
     x-go-name: "ContainerWaitOKBody"
     title: "ContainerWaitResponse"
-    required: [StatusCode, Error]
+    required: [StatusCode]
     properties:
       StatusCode:
         description: "Exit code of the container"
@@ -7089,35 +7174,6 @@ paths:
             type: "array"
             items:
               $ref: "#/definitions/ImageSummary"
-          examples:
-            application/json:
-              - Id: "sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
-                ParentId: ""
-                RepoTags:
-                  - "ubuntu:12.04"
-                  - "ubuntu:precise"
-                RepoDigests:
-                  - "ubuntu@sha256:992069aee4016783df6345315302fa59681aae51a8eeb2f889dea59290f21787"
-                Created: 1474925151
-                Size: 103579269
-                VirtualSize: 103579269
-                SharedSize: 0
-                Labels: {}
-                Containers: 2
-              - Id: "sha256:3e314f95dcace0f5e4fd37b10862fe8398e3c60ed36600bc0ca5fda78b087175"
-                ParentId: ""
-                RepoTags:
-                  - "ubuntu:12.10"
-                  - "ubuntu:quantal"
-                RepoDigests:
-                  - "ubuntu@sha256:002fba3e3255af10be97ea26e476692a7ebed0bb074a9ab960b2e7a1526b15d7"
-                  - "ubuntu@sha256:68ea0200f0b90df725d99d823905b04cf844f6039ef60c60bf3e019915017bd3"
-                Created: 1403128455
-                Size: 172064416
-                VirtualSize: 172064416
-                SharedSize: 0
-                Labels: {}
-                Containers: 5
         500:
           description: "server error"
           schema: