From 7fba6fdc4bd6b2a540e035f8d69f2c6725e42448 Mon Sep 17 00:00:00 2001
From: zhufl <zhu.fanglei@zte.com.cn>
Date: Fri, 9 Nov 2018 14:00:59 +0800
Subject: [PATCH] api-ref: fix some issues in volumes interfaces

1. group_id is missing from the response of list-voluems and create_volume.

2. shared_targets and service_uuid are new in 3.48

3. migration_status, os-vol-host-attr:host, os-vol-mig-status-attr:migstat,
   and os-vol-mig-status-attr:name_id may not always be present, so they
   should be optional parameters.

https://developer.openstack.org/api-ref/block-storage/v3/index.html?expanded=reset-a-backup-s-status-detail,update-a-backup-detail,create-a-backup-detail#create-a-volume
https://developer.openstack.org/api-ref/block-storage/v3/index.html?expanded=reset-a-backup-s-status-detail,update-a-backup-detail,create-a-backup-detail#show-a-volume-s-details

Change-Id: I11201f2a604818e633eb2000b3c69162c668721d
---
 api-ref/source/v2/parameters.yaml                  |  6 +++---
 api-ref/source/v3/parameters.yaml                  | 14 +++++++++++---
 .../v3/samples/volumes-list-detailed-response.json |  6 ++++--
 api-ref/source/v3/volumes-v3-volumes.inc           |  4 +++-
 4 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml
index f84544e2973..7f6ebe9871f 100644
--- a/api-ref/source/v2/parameters.yaml
+++ b/api-ref/source/v2/parameters.yaml
@@ -1322,21 +1322,21 @@ os-vol-host-attr:host:
     Current back-end of the volume.
     Host format is ``host@backend#pool``.
   in: body
-  required: true
+  required: false
   type: string
 os-vol-mig-status-attr:migstat:
   description: |
     The status of this volume migration (None means
     that a migration is not currently in progress).
   in: body
-  required: true
+  required: false
   type: string
 os-vol-mig-status-attr:name_id:
   description: |
     The volume ID that this volume name on the back-
     end is based on.
   in: body
-  required: true
+  required: false
   type: string
 os-vol-tenant-attr:tenant_id:
   description: |
diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index ad9f3a11c17..f636e98eb4a 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@@ -1142,6 +1142,12 @@ group_id:
   in: body
   required: true
   type: string
+group_id_optional:
+  description: |
+    The ID of the group.
+  in: body
+  required: false
+  type: string
 group_name:
   description: |
     The group name.
@@ -2050,21 +2056,21 @@ os-vol-host-attr:host:
     Current back-end of the volume.
     Host format is ``host@backend#pool``.
   in: body
-  required: true
+  required: false
   type: string
 os-vol-mig-status-attr:migstat:
   description: |
     The status of this volume migration (None means
     that a migration is not currently in progress).
   in: body
-  required: true
+  required: false
   type: string
 os-vol-mig-status-attr:name_id:
   description: |
     The volume ID that this volume name on the back-
     end is based on.
   in: body
-  required: true
+  required: false
   type: string
 os-vol-tenant-attr:tenant_id:
   description: |
@@ -2427,6 +2433,7 @@ service_uuid:
   in: body
   required: true
   type: string
+  min_version: 3.48
 services:
   description: |
     A list of service objects.
@@ -2440,6 +2447,7 @@ shared_targets:
   in: body
   required: true
   type: boolean
+  min_version: 3.48
 size:
   description: |
     The size of the volume, in gibibytes (GiB).
diff --git a/api-ref/source/v3/samples/volumes-list-detailed-response.json b/api-ref/source/v3/samples/volumes-list-detailed-response.json
index aafa710cce5..82a21d737ce 100644
--- a/api-ref/source/v3/samples/volumes-list-detailed-response.json
+++ b/api-ref/source/v3/samples/volumes-list-detailed-response.json
@@ -45,7 +45,8 @@
             "name": "test-volume-attachments",
             "bootable": "false",
             "created_at": "2015-11-29T03:01:44.000000",
-            "volume_type": "lvmdriver-1"
+            "volume_type": "lvmdriver-1",
+            "group_id": "8fbe5733-eb03-4c88-9ef9-f32b7d03a5e4"
         },
         {
             "migration_status": null,
@@ -92,7 +93,8 @@
             "name": "test-volume",
             "bootable": "true",
             "created_at": "2015-11-29T02:25:18.000000",
-            "volume_type": "lvmdriver-1"
+            "volume_type": "lvmdriver-1",
+            "group_id": "8fbe5733-eb03-4c88-9ef9-f32b7d03a5e4"
         }
     ],
     "volumes_links": [{
diff --git a/api-ref/source/v3/volumes-v3-volumes.inc b/api-ref/source/v3/volumes-v3-volumes.inc
index 513bd72a103..f45e5b47da6 100644
--- a/api-ref/source/v3/volumes-v3-volumes.inc
+++ b/api-ref/source/v3/volumes-v3-volumes.inc
@@ -101,7 +101,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - migration_status: migration_status_req
+   - migration_status: migration_status
    - attachments: attachments
    - links: links_vol
    - availability_zone: availability_zone
@@ -128,6 +128,7 @@ Response Parameters
    - created_at: created_at
    - volumes: volumes
    - volume_type: volume_type_vol
+   - group_id: group_id_optional
    - volumes_links: links_vol_optional
    - count: count
 
@@ -242,6 +243,7 @@ Response Parameters
    - bootable: bootable_response
    - created_at: created_at
    - volume_type: volume_type_vol
+   - group_id: group_id_optional
 
 Response Example
 ----------------