api: improve documentation of ContainerConfig type

ContainerConfig is used in multiple locations (for example, both for
Image.Config and Image.ContainerConfig). Unfortunately, swagger does
not allow documenting individual uses if a type is used; for this type,
the content is _optional_ when used as Image.ContainerConfig (which is
set by the classic builder, which does a "commit" of a container, but
not used when building an image with BuildKit).

This patch attempts to address this confusion by documenting that
"it may be empty (or fields not propagated) if it's used for the
Image.ContainerConfig field".

Perhaps alternatives are possible (aliasing the type?) but we can
look at those in a follow-up.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

api/swagger.yaml

@@ -1154,6 +1154,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:

api/types/types.go

@@ -73,8 +73,11 @@ type ImageInspect struct {
 	// Depending on how the image was created, this field may be empty.
 	Container string
 
-	// ContainerConfig is the configuration of the container that was committed
-	// into the 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.
 	ContainerConfig *container.Config
 
 	// DockerVersion is the version of Docker that was used to build the image.