Add doc for service disable reason

Change-Id: Ie2774a16323cf03a741583165fc7079cc8ca096d

api-ref/source/parameters.yaml

@@ -3049,12 +3049,27 @@ service_disable_host_response:
   in: body
   required: true
   type: string
+service_disable_reason_request:
+  description: |
+    A reason for the service being disabled.
+  in: body
+  required: false
+  type: string
+  min_version: 2.83
+service_disable_reason_response:
+  description: |
+    A reason for the service being disabled.
+  in: body
+  required: true
+  type: string
+  min_version: 2.83
 service_disabled_response:
   description: |
     Indicates whether the service is disabled.
   in: body
   required: true
   type: boolean
+  max_version: 2.82
 service_enable_binary_request:
   description: |
     The name of the service binary that you want to
@@ -3105,6 +3120,14 @@ service_state_response:
   in: body
   required: true
   type: string
+service_status_new_response:
+  description: |
+    The service status, which is ``enabled`` or
+    ``disabled``.
+  in: body
+  required: true
+  type: string
+  min_version: 2.83
 service_status_response:
   description: |
     The service status, which is ``enabled`` or

api-ref/source/samples/service-disable-request.json

@@ -1,4 +1,5 @@
 {
     "binary": "manila-share",
-    "host": "openstackhost@generic#pool_0"
+    "host": "openstackhost@generic#pool_0",
+    "disabled_reason": "Service taken down for maintenance until May"
 }

api-ref/source/samples/service-disable-response.json

@@ -1,5 +1,6 @@
 {
-    "disabled": true,
     "binary": "manila-share",
-    "host": "openstackhost@generic#pool_0"
+    "host": "openstackhost@generic#pool_0",
+    "status": "disabled",
+    "disabled_reason": "Service taken down for maintenance until May"
 }

api-ref/source/samples/service-enable-response.json

@@ -1,5 +1,6 @@
 {
-    "disabled": false,
     "binary": "manila-share",
-    "host": "openstackhost@generic#pool_0"
+    "host": "openstackhost@generic#pool_0",
+    "status": "enabled",
+    "disabled_reason": ""
 }

api-ref/source/services.inc

@@ -11,6 +11,11 @@ These APIs help in interacting with the Shared File Systems services,
     For API versions 2.6 and prior, replace ``services`` in the URLs
     with ``os-services``.
 
+.. note::
+  Starting from API version 2.83, ``disabled`` field will be replaced
+  by ``status`` field in response of enable or disable service request.
+  Re-enabling a disabled service will automatically clear ``disable reason``.
+
 
 List services
 ~~~~~~~~~~~~~
@@ -57,6 +62,7 @@ Response parameters
    - host: service_host_response
    - state: service_state_response
    - updated_at: updated_at
+   - disabled_reason: service_disable_reason_response
 
 Response example
 ----------------
@@ -109,6 +115,8 @@ Response parameters
    - host: service_enable_host_response
    - binary: service_binary_response
    - disabled: service_disabled_response
+   - status: service_status_new_response
+   - disabled_reason: service_disable_reason_response
 
 Response example
 ----------------
@@ -146,6 +154,7 @@ Request
    - project_id: project_id_path
    - binary: service_disable_binary_request
    - host: service_disable_host_request
+   - disabled_reason: service_disable_reason_request
 
 Request example
 ---------------
@@ -161,6 +170,8 @@ Response parameters
    - host: service_disable_host_response
    - binary: service_disable_binary_response
    - disabled: service_disabled_response
+   - status: service_status_new_response
+   - disabled_reason: service_disable_reason_response
 
 Response example
 ----------------

manila/api/v2/services.py

@@ -131,7 +131,7 @@ class ServiceControllerLegacy(ServiceMixin, wsgi.Controller):
 
     @wsgi.Controller.api_version('1.0', '2.6')
     def update(self, req, id, body):
-        return self._update(req, id, body)
+        return self._update(req, id, body, support_disabled_reason=False)
 
 
 class ServiceController(ServiceMixin, wsgi.Controller):