[api-ref] Refactor limits and services API

This patch refactors limits and services API to make it clear to
understand and maintain.

Change-Id: I0e214f59e193f861e4959dfef951854bea530b7b

api-ref/source/limits.inc

@@ -45,7 +45,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - tenant_id: tenant_id_1
+   - tenant_id: tenant_id_path
 
 Response parameters
 -------------------

api-ref/source/parameters.yaml

@@ -295,6 +295,39 @@ project_id_6:
   in: query
   required: false
   type: string
+service_binary_query:
+  description: |
+    The service binary name. Default is the base name
+    of the executable.
+  in: query
+  required: false
+  type: string
+service_host_query:
+  description: |
+    The service host name.
+  in: query
+  required: false
+  type: string
+service_state_query:
+  description: |
+    The current state of the service. A valid value
+    is ``up`` or ``down``.
+  in: query
+  required: false
+  type: string
+service_status_query:
+  description: |
+    The service status, which is ``enabled`` or
+    ``disabled``.
+  in: query
+  required: false
+  type: string
+service_zone_query:
+  description: |
+    The availability zone.
+  in: query
+  required: false
+  type: string
 share_network_id_5:
   description: |
     The UUID of the share network.
@@ -568,13 +601,6 @@ binary:
   in: body
   required: true
   type: string
-binary:
-  description: |
-    The name of the service binary that you want to
-    disable. Typically, this name is the base name of the executable.
-  in: body
-  required: true
-  type: string
 binary_1:
   description: |
     The name of the service binary that you want to
@@ -1480,7 +1506,7 @@ host_4:
   type: string
 host_5:
   description: |
-    The host name.
+    The service host name.
   in: body
   required: true
   type: string
@@ -2190,6 +2216,73 @@ server_pools_mapping:
   in: body
   required: true
   type: object
+service_binary_response:
+  description: |
+    The service binary name. Default is the base name
+    of the executable.
+  in: body
+  required: true
+  type: string
+service_disable_binary_request:
+  description: |
+    The name of the service binary that you want to
+    disable. Typically, this name is the base name of the executable.
+  in: body
+  required: true
+  type: string
+service_disable_binary_response:
+  description: |
+    The name of the disabled service binary.
+    Typically, this name is the base name of the executable.
+  in: body
+  required: true
+  type: string
+service_disable_host_request:
+  description: |
+    The host name of the service that you want to
+    disable.
+  in: body
+  required: true
+  type: string
+service_disable_host_response:
+  description: |
+    The host name of the disabled service.
+  in: body
+  required: true
+  type: string
+service_disabled_response:
+  description: |
+    Indicates whether the service is disabled.
+  in: body
+  required: true
+  type: boolean
+service_enable_binary_request:
+  description: |
+    The name of the service binary that you want to
+    enable. Typically, this name is the base name of the executable.
+  in: body
+  required: true
+  type: string
+service_enable_binary_response:
+  description: |
+    The name of the enabled service binary.
+    Typically, this name is the base name of the executable.
+  in: body
+  required: true
+  type: string
+service_enable_host_request:
+  description: |
+    The host name of the service that you want to
+    enable.
+  in: body
+  required: true
+  type: string
+service_enable_host_response:
+  description: |
+    The host name of the enabled service.
+  in: body
+  required: true
+  type: string
 service_host:
   description: |
     The manage-share service host in this format:
@@ -2199,6 +2292,56 @@ service_host:
   in: body
   required: true
   type: string
+service_host_response:
+  description: |
+    The service host name.
+  in: body
+  required: true
+  type: string
+service_id_response:
+  description: |
+    The service ID.
+  in: body
+  required: true
+  type: integer
+service_state_response:
+  description: |
+    The current state of the service. A valid value
+    is ``up`` or ``down``.
+  in: body
+  required: true
+  type: string
+service_status_response:
+  description: |
+    The service status, which is ``enabled`` or
+    ``disabled``.
+  in: body
+  required: true
+  type: string
+service_updated_at:
+  description: |
+    The date and time stamp when the service was updated.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    The ``±hh:mm`` value, if included, returns the time zone as an
+    offset from UTC.
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+  in: body
+  required: true
+  type: string
+service_zone_response:
+  description: |
+    The service availability zone.
+  in: body
+  required: true
+  type: string
 services:
   description: |
     Top element in the response body.

api-ref/source/services.inc

@@ -28,12 +28,12 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - tenant_id: tenant_id_1
-   - host: host_12
-   - binary: binary_3
-   - zone: zone_1
-   - state: state_2
-   - status: status_17
+   - tenant_id: tenant_id_path
+   - host: service_host_query
+   - binary: service_binary_query
+   - zone: service_zone_query
+   - state: service_state_query
+   - status: service_status_query
 
 Response parameters
 -------------------
@@ -41,13 +41,13 @@ Response parameters
 .. rest_parameters:: parameters.yaml
 
    - services: services
-   - id: id_12
-   - status: status_4
-   - binary: binary_2
-   - zone: zone
-   - host: host_5
-   - state: state_1
-   - updated_at: updated_at_5
+   - id: service_id_response
+   - status: service_status_response
+   - binary: service_binary_response
+   - zone: service_zone_response
+   - host: service_host_response
+   - state: service_state_response
+   - updated_at: service_updated_at
 
 Response example
 ----------------
@@ -72,9 +72,9 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - tenant_id: tenant_id_1
-   - binary: binary_1
-   - host: host_3
+   - tenant_id: tenant_id_path
+   - binary: service_enable_binary_request
+   - host: service_enable_host_request
 
 Request example
 ---------------
@@ -87,9 +87,9 @@ Response parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - host: host_14
-   - binary: binary_5
-   - disabled: disabled
+   - host: service_enable_host_response
+   - binary: service_binary_response
+   - disabled: service_disabled_response
 
 Response example
 ----------------
@@ -114,9 +114,9 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - tenant_id: tenant_id_1
-   - binary: binary
-   - host: host_2
+   - tenant_id: tenant_id_path
+   - binary: service_disable_binary_request
+   - host: service_disable_host_request
 
 Request example
 ---------------
@@ -129,9 +129,9 @@ Response parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - host: host_13
-   - binary: binary_4
-   - disabled: disabled
+   - host: service_disable_host_response
+   - binary: service_disable_binary_response
+   - disabled: service_disabled_response
 
 Response example
 ----------------