From c549325bd2d9df21af46c2703a55a0ff97f5bfcc Mon Sep 17 00:00:00 2001
From: Matt Riedemann <mriedem.os@gmail.com>
Date: Thu, 9 May 2019 09:26:09 -0400
Subject: [PATCH] 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        | 8 +-------
 api-ref/source/v3/parameters.yaml        | 8 +-------
 api-ref/source/v3/volume-manage.inc      | 2 +-
 api-ref/source/v3/volumes-v3-volumes.inc | 6 +++---
 4 files changed, 6 insertions(+), 18 deletions(-)

diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml
index 3692ec8cfb3..170a19cda5b 100644
--- a/api-ref/source/v2/parameters.yaml
+++ b/api-ref/source/v2/parameters.yaml
@@ -1064,13 +1064,7 @@ migration_policy:
   type: string
 migration_status:
   description: |
-    The volume migration status.
-  in: body
-  required: true
-  type: string
-migration_status_1:
-  description: |
-    The volume migration status.
+    The volume migration status. Admin only.
   in: body
   required: false
   type: string
diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index b154ee543ed..400cd2a7b46 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/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.
diff --git a/api-ref/source/v3/volume-manage.inc b/api-ref/source/v3/volume-manage.inc
index 1a28e3c0108..eb0dd457626 100644
--- a/api-ref/source/v3/volume-manage.inc
+++ b/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
diff --git a/api-ref/source/v3/volumes-v3-volumes.inc b/api-ref/source/v3/volumes-v3-volumes.inc
index e6c0cc96f75..487da8d1515 100644
--- a/api-ref/source/v3/volumes-v3-volumes.inc
+++ b/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