Add api-ref for ensure shares API

This change updates the documentation for the ensure shares APIs.
The side effects such as the shares status updates and the new
field will be added to the admin documentation as well.

Change-Id: I3c550b5f77356f89a8c3bdad9fb5c67f1fe8ff4a
Signed-off-by: Carlos Eduardo <ces.eduardo98@gmail.com>

api-ref/source/parameters.yaml

@@ -3088,6 +3088,20 @@ service_enable_host_response:
   in: body
   required: true
   type: string
+service_ensure_shares_host_request:
+  description: |
+    The host name of the manila-share binary that you want to
+    start the ensure shares procedure in the ``host@backend`` format.
+  in: body
+  required: true
+  type: string
+service_ensuring_response:
+  description: |
+    Whether the service is currently running ensure shares or not.
+  in: body
+  required: true
+  type: string
+  min_version: 2.86
 service_host:
   description: |
     The manage-share service host in this format:

api-ref/source/samples/service-ensure-shares-request.json

@@ -0,0 +1,3 @@
+{
+    "host": "openstackhost@storagebackend"
+}

api-ref/source/services.inc

@@ -63,6 +63,7 @@ Response parameters
    - state: service_state_response
    - updated_at: updated_at
    - disabled_reason: service_disable_reason_response
+   - ensuring: service_ensuring_response
 
 Response example
 ----------------
@@ -178,3 +179,45 @@ Response example
 
 .. literalinclude:: samples/service-disable-response.json
    :language: javascript
+
+
+Ensure shares (Since API Version 2.86)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v2/services/ensure-shares
+
+Starts the ensure shares procedure for a manila-share binary.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - host: service_ensure_shares_host_request
+
+Request example
+---------------
+
+.. literalinclude:: samples/service-ensure-shares-request.json
+   :language: javascript
+
+Response parameters
+-------------------
+
+There is no body content for the response.