api: swagger: document ImageSummary fields

Also fixes a typo in ImageInspect :)

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

api/swagger.yaml

@@ -1600,7 +1600,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).
 
@@ -1788,41 +1788,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"
@@ -7542,35 +7620,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:

api/types/image_summary.go

@@ -7,43 +7,91 @@ package types
 // swagger:model ImageSummary
 type ImageSummary struct {
 
-	// containers
+	// 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.
+	//
 	// Required: true
 	Containers int64 `json:"Containers"`
 
-	// created
+	// Date and time at which the image was created as a Unix timestamp
+	// (number of seconds sinds EPOCH).
+	//
 	// Required: true
 	Created int64 `json:"Created"`
 
-	// Id
+	// 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.
+	//
 	// Required: true
 	ID string `json:"Id"`
 
-	// labels
+	// User-defined key/value metadata.
 	// Required: true
 	Labels map[string]string `json:"Labels"`
 
-	// parent Id
+	// 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.
+	//
 	// Required: true
 	ParentID string `json:"ParentId"`
 
-	// repo digests
+	// 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.
+	//
 	// Required: true
 	RepoDigests []string `json:"RepoDigests"`
 
-	// repo tags
+	// 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.
+	//
 	// Required: true
 	RepoTags []string `json:"RepoTags"`
 
-	// shared size
+	// 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.
+	//
 	// Required: true
 	SharedSize int64 `json:"SharedSize"`
 
-	// size
+	// Total size of the image including all layers it is composed of.
+	//
 	// Required: true
 	Size int64 `json:"Size"`
 
-	// virtual size
+	// 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.
+	//
 	// Required: true
 	VirtualSize int64 `json:"VirtualSize"`
 }

api/types/types.go

@@ -28,7 +28,7 @@ type RootFS struct {
 type ImageInspect struct {
 	// 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).
 	//