From dbd1efd74452d3daa6b2d72bec2b1e5f6e6a6d20 Mon Sep 17 00:00:00 2001
From: Matt Riedemann <mriedem.os@gmail.com>
Date: Thu, 23 Mar 2017 16:00:46 -0400
Subject: [PATCH] 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 |  4 ++--
 api-ref/source/parameters.yaml           | 21 +++++++++++++++++++--
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/api-ref/source/os-volume-attachments.inc b/api-ref/source/os-volume-attachments.inc
index 62bdde04dfaf..a2bdd92be91d 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 18c3164bb962..a70a041b05aa 100644
--- a/api-ref/source/parameters.yaml
+++ b/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