diff --git a/api-ref/source/os-volume-attachments.inc b/api-ref/source/os-volume-attachments.inc
index 426270328417..4ee52a60480e 100644
--- a/api-ref/source/os-volume-attachments.inc
+++ b/api-ref/source/os-volume-attachments.inc
@@ -64,7 +64,7 @@ Request
 .. rest_parameters:: parameters.yaml
 
   - server_id: server_id_path
-  - volumeAttachment: volumeAttachment
+  - volumeAttachment: volumeAttachment_post
   - volumeId: volumeId
   - device: device
 
@@ -142,7 +142,7 @@ Request
 
   - server_id: server_id_path
   - attachment_id: attachment_id
-  - volumeAttachment: volumeAttachment
+  - volumeAttachment: volumeAttachment_put
   - volumeId: volumeId_swap
 
 **Example Update a volume attachment: JSON request**
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 1bd117a3bf4b..cbf730ae500a 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -5005,10 +5005,27 @@ volume_type_optional:
   in: body
   required: false
   type: string
+# This is the volumeAttachment in a response body.
 volumeAttachment:
   description: |
-    A dictionary representation of a volume attachment containing the fields,
-    ``device``, ``id``, ``serverId``, ``volumeId``.
+    A dictionary representation of a volume attachment containing the fields
+    ``device``, ``id``, ``serverId`` and ``volumeId``.
+  in: body
+  required: true
+  type: object
+# This is the volumeAttachment in a POST (attach volume) request body.
+volumeAttachment_post:
+  description: |
+    A dictionary representation of a volume attachment containing the fields
+    ``device`` and ``volumeId``.
+  in: body
+  required: true
+  type: object
+# This is the volumeAttachment in a PUT (swap volume) request body.
+volumeAttachment_put:
+  description: |
+    A dictionary representation of a volume attachment containing the field
+    ``volumeId``.
   in: body
   required: true
   type: object