api-ref: mark migration_status parameter as optional

Everything that goes through the volumes view builder
detail() method has a strict is_admin check on returning
the migration_status parameter [1]. This means the
migration_status parameter in the API reference should
be optional since it's admin-only and not always shown.

This fixes the v2 and v3 API references for showing,
creating, updating, resetting the status of, and creating
from a managed volume. As a result, the parameter for a
required migration_status parameter is unused and removed.

Note that there is no strict policy check on the
migration_status request parameter when resetting a volume's
status, but the action itself is admin-only by default
using the volume_extension:volume_admin_actions:reset_status
policy rule.

[1] https://opendev.org/openstack/cinder/src/tag/14.0.0/cinder/api/v2/views/volumes.py#L94

Change-Id: I82308dc1a6aaf039b675a17e19747f11be574209
Closes-Bug: #1828113

api-ref/source/v2/parameters.yaml

@@ -1064,13 +1064,7 @@ migration_policy:
   type: string
 migration_status:
   description: |
-    The volume migration status.
+    The volume migration status. Admin only.
-  in: body
-  required: true
-  type: string
-migration_status_1:
-  description: |
-    The volume migration status.
   in: body
   required: false
   type: string

api-ref/source/v3/parameters.yaml

@@ -1797,16 +1797,10 @@ migration_policy:
   type: string
 migration_status:
   description: |
-    The volume migration status.
+    The volume migration status. Admin only.
   in: body
   required: false
   type: string
-migration_status_req:
-  description: |
-    The volume migration status.
-  in: body
-  required: true
-  type: string
 mountpoint:
   description: |
     The attaching mount point.

api-ref/source/v3/volume-manage.inc

@@ -70,7 +70,7 @@ Response
 
    - volume: volume
    - status: status_vol
-   - migration_status: migration_status_req
+   - migration_status: migration_status
    - user_id: user_id
    - attachments: attachments
    - links: links_vol

api-ref/source/v3/volumes-v3-volumes.inc

@@ -221,7 +221,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
@@ -344,7 +344,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
@@ -424,7 +424,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