api: swagger: document BuildCache fields (API v1.42)

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

docs/api/v1.42.yaml

@@ -2247,23 +2247,63 @@ definitions:
 
   BuildCache:
     type: "object"
+    description: |
+      BuildCache contains information about a build cache record.
     properties:
       ID:
         type: "string"
+        description: |
+          Unique ID of the build cache record.
+        example: "ndlpt0hhvkqcdfkputsk4cq9c"
       Parent:
+        description: |
+          ID of the parent build cache record.
+
+          > **Deprecated**: This field is deprecated, and omitted if empty.
         type: "string"
+        x-nullable: true
+        example: ""
+      Parents:
+        description: |
+          List of parent build cache record IDs.
+        type: "array"
+        items:
+          type: "string"
+        x-nullable: true
+        example: ["hw53o5aio51xtltp5xjp8v7fx"]
       Type:
         type: "string"
+        description: |
+          Cache record type.
+        example: "regular"
+        # see https://github.com/moby/buildkit/blob/fce4a32258dc9d9664f71a4831d5de10f0670677/client/diskusage.go#L75-L84
+        enum:
+          - "internal"
+          - "frontend"
+          - "source.local"
+          - "source.git.checkout"
+          - "exec.cachemount"
+          - "regular"
       Description:
         type: "string"
+        description: |
+          Description of the build-step that produced the build cache.
+        example: "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache"
       InUse:
         type: "boolean"
+        description: |
+          Indicates if the build cache is in use.
+        example: false
       Shared:
         type: "boolean"
+        description: |
+          Indicates if the build cache is shared.
+        example: true
       Size:
         description: |
           Amount of disk space used by the build cache (in bytes).
         type: "integer"
+        example: 51
       CreatedAt:
         description: |
           Date and time at which the build cache was created in
@@ -2281,6 +2321,7 @@ definitions:
         example: "2017-08-09T07:09:37.632105588Z"
       UsageCount:
         type: "integer"
+        example: 26
 
   ImageID:
     type: "object"
@@ -9035,7 +9076,7 @@ paths:
               BuildCache:
                 -
                   ID: "hw53o5aio51xtltp5xjp8v7fx"
-                  Parent: ""
+                  Parents: []
                   Type: "regular"
                   Description: "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0"
                   InUse: false
@@ -9046,7 +9087,7 @@ paths:
                   UsageCount: 26
                 -
                   ID: "ndlpt0hhvkqcdfkputsk4cq9c"
-                  Parent: "hw53o5aio51xtltp5xjp8v7fx"
+                  Parents: ["ndlpt0hhvkqcdfkputsk4cq9c"]
                   Type: "regular"
                   Description: "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache"
                   InUse: false