api: swagger: document MountPoint fields

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

api/swagger.yaml

@@ -202,24 +202,72 @@ definitions:
 
   MountPoint:
     type: "object"
-    description: "A mount point inside a container"
+    description: |
+      MountPoint represents a mount point configuration inside the container.
+      This is used for reporting the mountpoints in use by a container.
     properties:
       Type:
+        description: |
+          The mount type:
+
+          - `bind` a mount of a file or directory from the host into the container.
+          - `volume` a docker volume with the given `Name`.
+          - `tmpfs` a `tmpfs`.
+          - `npipe` a named pipe from the host into the container.
         type: "string"
+        enum:
+          - "bind"
+          - "volume"
+          - "tmpfs"
+          - "npipe"
+        example: "volume"
       Name:
+        description: |
+          Name is the name reference to the underlying data defined by `Source`
+          e.g., the volume name.
         type: "string"
+        example: "myvolume"
       Source:
+        description: |
+          Source location of the mount.
+
+          For volumes, this contains the storage location of the volume (within
+          `/var/lib/docker/volumes/`). For bind-mounts, and `npipe`, this contains
+          the source (host) part of the bind-mount. For `tmpfs` mount points, this
+          field is empty.
         type: "string"
+        example: "/var/lib/docker/volumes/myvolume/_data"
       Destination:
+        description: |
+          Destination is the path relative to the container root (`/`) where
+          the `Source` is mounted inside the container.
         type: "string"
+        example: "/usr/share/nginx/html/"
       Driver:
+        description: |
+          Driver is the volume driver used to create the volume (if it is a volume).
         type: "string"
+        example: "local"
       Mode:
+        description: |
+          Mode is a comma separated list of options supplied by the user when
+          creating the bind/volume mount.
+
+          The default is platform-specific (`"z"` on Linux, empty on Windows).
         type: "string"
+        example: "z"
       RW:
+        description: |
+          Whether the mount is mounted writable (read-write).
         type: "boolean"
+        example: true
       Propagation:
+        description: |
+          Propagation describes how mounts are propagated from the host into the
+          mount point, and vice-versa. Refer to the [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt)
+          for details. This field is not used on Windows.
         type: "string"
+        example: ""
 
   DeviceMapping:
     type: "object"