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

@@ -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: |

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).

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": [{

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