Merge pull request #42621 from gesellix/swagger-wip

Improve swagger.yaml to match the 1.41 api version

api/swagger.yaml

@@ -382,11 +382,13 @@ definitions:
         type: "string"
         description: |
           - Empty string means not to restart
+          - `no` Do not automatically restart
           - `always` Always restart
           - `unless-stopped` Restart always except when the user has manually stopped the container
           - `on-failure` Restart only when the container exit code is non-zero
         enum:
           - ""
+          - "no"
           - "always"
           - "unless-stopped"
           - "on-failure"
@@ -2188,6 +2190,24 @@ definitions:
         type: "string"
         x-nullable: false
 
+  PluginPrivilegeItem:
+    description: |
+      Describes a permission the user has to accept upon installing
+      the plugin.
+    type: "object"
+    properties:
+      Name:
+        type: "string"
+        example: "network"
+      Description:
+        type: "string"
+      Value:
+        type: "array"
+        items:
+          type: "string"
+        example:
+          - "host"
+
   Plugin:
     description: "A plugin for the Engine API"
     type: "object"
@@ -2970,19 +2990,7 @@ definitions:
           PluginPrivilege:
             type: "array"
             items:
-              description: |
-                Describes a permission accepted by the user upon installing the
-                plugin.
-              type: "object"
-              properties:
-                Name:
-                  type: "string"
-                Description:
-                  type: "string"
-                Value:
-                  type: "array"
-                  items:
-                    type: "string"
+              $ref: "#/definitions/PluginPrivilegeItem"
       ContainerSpec:
         type: "object"
         description: |
@@ -4022,73 +4030,71 @@ definitions:
       Warning: "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
 
   ContainerSummary:
-    type: "array"
-    items:
-      type: "object"
-      properties:
-        Id:
-          description: "The ID of this container"
-          type: "string"
-          x-go-name: "ID"
-        Names:
-          description: "The names that this container has been given"
-          type: "array"
-          items:
-            type: "string"
-        Image:
-          description: "The name of the image used when creating this container"
-          type: "string"
-        ImageID:
-          description: "The ID of the image that this container was created from"
+    type: "object"
+    properties:
+      Id:
+        description: "The ID of this container"
+        type: "string"
+        x-go-name: "ID"
+      Names:
+        description: "The names that this container has been given"
+        type: "array"
+        items:
           type: "string"
-        Command:
-          description: "Command to run when starting the container"
+      Image:
+        description: "The name of the image used when creating this container"
+        type: "string"
+      ImageID:
+        description: "The ID of the image that this container was created from"
+        type: "string"
+      Command:
+        description: "Command to run when starting the container"
+        type: "string"
+      Created:
+        description: "When the container was created"
+        type: "integer"
+        format: "int64"
+      Ports:
+        description: "The ports exposed by this container"
+        type: "array"
+        items:
+          $ref: "#/definitions/Port"
+      SizeRw:
+        description: "The size of files that have been created or changed by this container"
+        type: "integer"
+        format: "int64"
+      SizeRootFs:
+        description: "The total size of all the files in this container"
+        type: "integer"
+        format: "int64"
+      Labels:
+        description: "User-defined key/value metadata."
+        type: "object"
+        additionalProperties:
           type: "string"
-        Created:
-          description: "When the container was created"
-          type: "integer"
-          format: "int64"
-        Ports:
-          description: "The ports exposed by this container"
-          type: "array"
-          items:
-            $ref: "#/definitions/Port"
-        SizeRw:
-          description: "The size of files that have been created or changed by this container"
-          type: "integer"
-          format: "int64"
-        SizeRootFs:
-          description: "The total size of all the files in this container"
-          type: "integer"
-          format: "int64"
-        Labels:
-          description: "User-defined key/value metadata."
-          type: "object"
-          additionalProperties:
+      State:
+        description: "The state of this container (e.g. `Exited`)"
+        type: "string"
+      Status:
+        description: "Additional human-readable status of this container (e.g. `Exit 0`)"
+        type: "string"
+      HostConfig:
+        type: "object"
+        properties:
+          NetworkMode:
             type: "string"
-        State:
-          description: "The state of this container (e.g. `Exited`)"
-          type: "string"
-        Status:
-          description: "Additional human-readable status of this container (e.g. `Exit 0`)"
-          type: "string"
-        HostConfig:
-          type: "object"
-          properties:
-            NetworkMode:
-              type: "string"
-        NetworkSettings:
-          description: "A summary of the container's network settings"
-          type: "object"
-          properties:
-            Networks:
-              type: "object"
-              additionalProperties:
-                $ref: "#/definitions/EndpointSettings"
-        Mounts:
-          type: "array"
-          items:
-            $ref: "#/definitions/Mount"
+      NetworkSettings:
+        description: "A summary of the container's network settings"
+        type: "object"
+        properties:
+          Networks:
+            type: "object"
+            additionalProperties:
+              $ref: "#/definitions/EndpointSettings"
+      Mounts:
+        type: "array"
+        items:
+          $ref: "#/definitions/Mount"
 
   Driver:
     description: "Driver represents a driver (network, logging, secrets)."
@@ -4366,7 +4372,6 @@ definitions:
         type: "string"
         example: "2020-06-22T15:49:27.000000000+00:00"
 
-
   SystemInfo:
     type: "object"
     properties:
@@ -5261,7 +5266,9 @@ paths:
         200:
           description: "no error"
           schema:
-            $ref: "#/definitions/ContainerSummary"
+            type: "array"
+            items:
+              $ref: "#/definitions/ContainerSummary"
           examples:
             application/json:
               - Id: "8dfafdbc3a40"
@@ -7505,6 +7512,18 @@ paths:
             Refer to the [authentication section](#section/Authentication) for
             details.
           type: "string"
+        - name: "changes"
+          in: "query"
+          description: |
+            Apply `Dockerfile` instructions to the image that is created,
+            for example: `changes=ENV DEBUG=true`.
+            Note that `ENV DEBUG=true` should be URI component encoded.
+
+            Supported `Dockerfile` instructions:
+            `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`
+          type: "array"
+          items:
+            type: "string"
         - name: "platform"
           in: "query"
           description: "Platform in the format os[/arch[/variant]]"
@@ -8531,6 +8550,7 @@ paths:
           description: "Exec configuration"
           schema:
             type: "object"
+            title: "ExecConfig"
             properties:
               AttachStdin:
                 type: "boolean"
@@ -8621,6 +8641,7 @@ paths:
           in: "body"
           schema:
             type: "object"
+            title: "ExecStartConfig"
             properties:
               Detach:
                 type: "boolean"
@@ -9155,6 +9176,7 @@ paths:
           required: true
           schema:
             type: "object"
+            title: "NetworkCreateRequest"
             required: ["Name"]
             properties:
               Name:
@@ -9265,6 +9287,7 @@ paths:
           required: true
           schema:
             type: "object"
+            title: "NetworkConnectRequest"
             properties:
               Container:
                 type: "string"
@@ -9311,6 +9334,7 @@ paths:
           required: true
           schema:
             type: "object"
+            title: "NetworkDisconnectRequest"
             properties:
               Container:
                 type: "string"
@@ -9395,20 +9419,7 @@ paths:
           schema:
             type: "array"
             items:
-              description: |
-                Describes a permission the user has to accept upon installing
-                the plugin.
-              type: "object"
-              title: "PluginPrivilegeItem"
-              properties:
-                Name:
-                  type: "string"
-                Description:
-                  type: "string"
-                Value:
-                  type: "array"
-                  items:
-                    type: "string"
+              $ref: "#/definitions/PluginPrivilegeItem"
             example:
               - Name: "network"
                 Description: ""
@@ -9484,19 +9495,7 @@ paths:
           schema:
             type: "array"
             items:
-              description: |
-                Describes a permission accepted by the user upon installing the
-                plugin.
-              type: "object"
-              properties:
-                Name:
-                  type: "string"
-                Description:
-                  type: "string"
-                Value:
-                  type: "array"
-                  items:
-                    type: "string"
+              $ref: "#/definitions/PluginPrivilegeItem"
             example:
               - Name: "network"
                 Description: ""
@@ -9668,19 +9667,7 @@ paths:
           schema:
             type: "array"
             items:
-              description: |
-                Describes a permission accepted by the user upon installing the
-                plugin.
-              type: "object"
-              properties:
-                Name:
-                  type: "string"
-                Description:
-                  type: "string"
-                Value:
-                  type: "array"
-                  items:
-                    type: "string"
+              $ref: "#/definitions/PluginPrivilegeItem"
             example:
               - Name: "network"
                 Description: ""
@@ -9970,6 +9957,7 @@ paths:
           required: true
           schema:
             type: "object"
+            title: "SwarmInitRequest"
             properties:
               ListenAddr:
                 description: |
@@ -10068,6 +10056,7 @@ paths:
           required: true
           schema:
             type: "object"
+            title: "SwarmJoinRequest"
             properties:
               ListenAddr:
                 description: |
@@ -10228,6 +10217,7 @@ paths:
           required: true
           schema:
             type: "object"
+            title: "SwarmUnlockRequest"
             properties:
               UnlockKey:
                 description: "The swarm's unlock key."
@@ -11349,14 +11339,14 @@ paths:
                 description: |
                   A descriptor struct containing digest, media type, and size.
                 properties:
-                  MediaType:
+                  mediaType:
                     type: "string"
-                  Size:
+                  size:
                     type: "integer"
                     format: "int64"
-                  Digest:
+                  digest:
                     type: "string"
-                  URLs:
+                  urls:
                     type: "array"
                     items:
                       type: "string"
@@ -11367,17 +11357,17 @@ paths:
                 items:
                   type: "object"
                   properties:
-                    Architecture:
+                    architecture:
                       type: "string"
-                    OS:
+                    os:
                       type: "string"
-                    OSVersion:
+                    os.version:
                       type: "string"
-                    OSFeatures:
+                    os.features:
                       type: "array"
                       items:
                         type: "string"
-                    Variant:
+                    variant:
                       type: "string"
                     Features:
                       type: "array"
@@ -11392,12 +11382,12 @@ paths:
                 URLs:
                   - ""
               Platforms:
-                - Architecture: "amd64"
-                  OS: "linux"
-                  OSVersion: ""
-                  OSFeatures:
+                - architecture: "amd64"
+                  os: "linux"
+                  os.version: ""
+                  os.features:
                     - ""
-                  Variant: ""
+                  variant: ""
                   Features:
                     - ""
         401: