Merge pull request #43339 from thaJeztah/api_improve_mountpoint_doc

api:  document MountPoint fields (swagger, godoc and docs)

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"

api/types/types.go

@@ -502,13 +502,44 @@ type DefaultNetworkSettings struct {
 // MountPoint represents a mount point configuration inside the container.
 // This is used for reporting the mountpoints in use by a container.
 type MountPoint struct {
+	// Type is the type of mount, see `Type<foo>` definitions in
+	// github.com/docker/docker/api/types/mount.Type
 	Type mount.Type `json:",omitempty"`
+
+	// Name is the name reference to the underlying data defined by `Source`
+	// e.g., the volume name.
 	Name string `json:",omitempty"`
+
+	// Source is the 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.
 	Source string
+
+	// Destination is the path relative to the container root (`/`) where the
+	// Source is mounted inside the container.
 	Destination string
+
+	// Driver is the volume driver used to create the volume (if it is a volume).
 	Driver string `json:",omitempty"`
+
+	// 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).
 	Mode string
+
+	// RW indicates whether the mount is mounted writable (read-write).
 	RW bool
+
+	// Propagation describes how mounts are propagated from the host into the
+	// mount point, and vice-versa. Refer to the Linux kernel documentation
+	// for details:
+	// https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt
+	//
+	// This field is not used on Windows.
 	Propagation mount.Propagation
 }
 

docs/api/v1.25.yaml

@@ -170,24 +170,70 @@ 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`.
         type: "string"
+        enum:
+          - "bind"
+          - "volume"
+          - "tmpfs"
+        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"

docs/api/v1.26.yaml

@@ -171,24 +171,70 @@ 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`.
         type: "string"
+        enum:
+          - "bind"
+          - "volume"
+          - "tmpfs"
+        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"

docs/api/v1.27.yaml

@@ -174,24 +174,70 @@ 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`.
         type: "string"
+        enum:
+          - "bind"
+          - "volume"
+          - "tmpfs"
+        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"

docs/api/v1.28.yaml

@@ -175,24 +175,70 @@ 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`.
         type: "string"
+        enum:
+          - "bind"
+          - "volume"
+          - "tmpfs"
+        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"

docs/api/v1.29.yaml

@@ -176,24 +176,70 @@ 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`.
         type: "string"
+        enum:
+          - "bind"
+          - "volume"
+          - "tmpfs"
+        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"

docs/api/v1.30.yaml

@@ -177,24 +177,70 @@ 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`.
         type: "string"
+        enum:
+          - "bind"
+          - "volume"
+          - "tmpfs"
+        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"

docs/api/v1.31.yaml

@@ -178,24 +178,70 @@ 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`.
         type: "string"
+        enum:
+          - "bind"
+          - "volume"
+          - "tmpfs"
+        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"

docs/api/v1.32.yaml

@@ -179,24 +179,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"

docs/api/v1.33.yaml

@@ -184,24 +184,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"

docs/api/v1.34.yaml

@@ -187,24 +187,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"

docs/api/v1.35.yaml

@@ -175,24 +175,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"

docs/api/v1.36.yaml

@@ -175,24 +175,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"

docs/api/v1.37.yaml

@@ -175,24 +175,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"

docs/api/v1.38.yaml

@@ -176,24 +176,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"

docs/api/v1.39.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"

docs/api/v1.40.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"

docs/api/v1.41.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"