api-ref: fix description of volumeAttachment for attach/swap-volume

The description of the volumeAttachment request parameter was actually
the description of the response parameter, which included more fields
than we allow on the POST and PUT requests for os-volume_attachments.

This fixes the descriptions for both POST and PUT and also includes a
tiny fix for the wording on the existing volumeAttachment parameter.

Change-Id: I4ccd4ac12e24b232925875fdb5fb568c2bfaf417
Closes-Bug: #1675536

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**

api-ref/source/parameters.yaml

@@ -4949,10 +4949,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