From 78dee1de596957ff06a7d4f08fcea83d891f973b Mon Sep 17 00:00:00 2001
From: ghanshyam <ghanshyammann@gmail.com>
Date: Fri, 24 Mar 2017 07:11:25 +0000
Subject: [PATCH] Fix api-ref for adminPass behavior

This commit fix the below doc issue for adminPass
 -'adminPass' attrbiure is only return in response if
  'enable_instance_password' configuration option is set to true
 - evacuate API stop returning adminPass from 2.14 microversion
   so max version for this field is 2.13.
 - if 'adminPass' is not present in request then, operation auto generate one.

Change-Id: I636657ed30b33da0a2df73b222c4ce5d8388a3d8
---
 api-ref/source/parameters.yaml             | 44 ++++++++++++----------
 api-ref/source/servers-action-evacuate.inc |  8 ++--
 api-ref/source/servers-actions.inc         |  6 +--
 api-ref/source/servers.inc                 |  3 +-
 4 files changed, 34 insertions(+), 27 deletions(-)

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 06b591b18f7d..c29db3432769 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1078,40 +1078,44 @@ addTenantAccess:
   in: body
   required: true
   type: string
-adminPass:
+adminPass_evacuate:
   description: |
-    The administrative password of the server.
-  in: body
-  required: true
-  type: string
-adminPass_evacuate_rebuild:
-  description: |
-    An administrative password to access the evacuated or rebuilt instance. To set the administrative
-    password, set the ``enable_instance_password`` configuration option to ``True``.
-    If you set this option to ``False`` and you try to set the administrative password,
-    the API does not set the password and the response shows a ``null`` value for
-    the ``adminPass`` parameter.
+    An administrative password to access the evacuated instance.
+    If you set ``enable_instance_password`` configuration option to ``False``,
+    the API wouldn't return the ``adminPass`` field in response.
   in: body
   required: false
   type: string
-  max_version: 2.14
-adminPass_evacuate_rebuild_request:
+  max_version: 2.13
+adminPass_evacuate_request:
   description: |
-    An administrative password to access the evacuated or rebuilt instance. To set the administrative
-    password, set the ``enable_instance_password`` configuration option to ``True``.
-    If you set this option to ``False`` and you try to set the administrative password,
-    the API does not set the password and the response shows a ``null`` value for
-    the ``adminPass`` parameter.
+    An administrative password to access the evacuated instance. If you omit this parameter, the operation
+    generates a new password.
   in: body
   required: false
   type: string
-adminPass_rescue:
+  max_version: 2.13
+adminPass_request:
+  description: |
+    The administrative password of the server. If you omit this parameter, the operation
+    generates a new password.
+  in: body
+  required: false
+  type: string
+adminPass_rescue_request:
   description: |
     The password for the rescued instance. If you omit this parameter, the operation
     generates a new password.
   in: body
   required: false
   type: string
+adminPass_response:
+  description: |
+    The administrative password for the server. If you set ``enable_instance_password`` configuration
+    option to ``False``, the API wouldn't return the ``adminPass`` field in response.
+  in: body
+  required: false
+  type: string
 agent:
   description: |
     The guest agent object.
diff --git a/api-ref/source/servers-action-evacuate.inc b/api-ref/source/servers-action-evacuate.inc
index a3c4a72a1f49..2252e62d33b8 100644
--- a/api-ref/source/servers-action-evacuate.inc
+++ b/api-ref/source/servers-action-evacuate.inc
@@ -1,3 +1,4 @@
+.. note:: Microversion 2.23 or greater is required for this API.
 .. -*- rst -*-
 
 Evacuate Server (evacuate Action)
@@ -24,7 +25,7 @@ Request
   - server_id: server_id_path
   - evacuate: evacuate
   - host: host
-  - adminPass: adminPass_evacuate_rebuild_request
+  - adminPass: adminPass_evacuate_request
   - onSharedStorage: on_shared_storage
   - force: force_evacuate
 
@@ -41,9 +42,10 @@ Response
 
 .. rest_parameters:: parameters.yaml
 
-  - adminPass: adminPass_evacuate_rebuild
+  - adminPass: adminPass_evacuate
+
+.. note:: API does not return any Response for Microversion 2.14 or greater.
 
-|
 
 **Example Evacuate Server (evacuate Action)**
 
diff --git a/api-ref/source/servers-actions.inc b/api-ref/source/servers-actions.inc
index dfdc065860aa..9d987b836ec3 100644
--- a/api-ref/source/servers-actions.inc
+++ b/api-ref/source/servers-actions.inc
@@ -409,7 +409,7 @@ Request
   - rebuild: rebuild
   - imageRef: imageRef
   - name: server_name_optional
-  - adminPass: adminPass_evacuate_rebuild
+  - adminPass: adminPass_request
   - metadata: metadata
   - personality: personality
   - preserve_ephemeral: preserve_ephemeral
@@ -533,7 +533,7 @@ Request
 
   - server_id: server_id_path
   - rescue: rescue
-  - adminPass: adminPass_rescue
+  - adminPass: adminPass_rescue_request
   - rescue_image_ref: rescue_image_ref
 
 **Example Rescue server**
@@ -546,7 +546,7 @@ Response
 
 .. rest_parameters:: parameters.yaml
 
-  - adminPass: adminPass
+  - adminPass: adminPass_response
 
 **Example Extended rescue server**
 
diff --git a/api-ref/source/servers.inc b/api-ref/source/servers.inc
index 551ac8f0b85d..16d79801a235 100644
--- a/api-ref/source/servers.inc
+++ b/api-ref/source/servers.inc
@@ -310,7 +310,7 @@ Request
   - metadata: metadata
   - accessIPv4: accessIPv4_in
   - accessIPv6: accessIPv6_in
-  - adminPass: adminPass
+  - adminPass: adminPass_request
   - user_data: user_data
   - availability_zone: os-availability-zone:availability_zone
   - networks: networks
@@ -389,6 +389,7 @@ Response
   - OS-EXT-SRV-ATTR:ramdisk_id: server_ramdisk_id
   - OS-EXT-SRV-ATTR:root_device_name: server_root_device_name
   - OS-EXT-SRV-ATTR:user_data: server_user_data
+  - adminPass: adminPass_response
 
 **Example Create Server**