api-ref host verification (os-hosts.inc)

This verify the os-hosts by adding more reponse param
descriptions and body.

Part of bp:api-ref-in-rst

Change-Id: Ifefd77c59ae4706d966ac08963ae1246ba038ca9

api-ref/source/os-hosts.inc

@@ -1,16 +1,17 @@
 .. -*- rst -*-
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 ==================
  Hosts (os-hosts)
 ==================
 
-Manages physical hosts. Some virt drivers don not support all host
+Manages physical hosts. Some virt drivers do not support all host
 functions. For more information, see `nova virt support
 matrix <http://docs.openstack.org/developer/nova/support-matrix.html>`__
 
+Policy defaults enable only users with the administrative role to perform
+all os-hosts related operations. Cloud providers can change these permissions
+through the ``policy.json`` file.
+
 List Hosts
 ==========
 
@@ -32,7 +33,14 @@ Request
 Response
 --------
 
-**Example List Hosts: JSON response**
+.. rest_parameters:: parameters.yaml
+
+  - hosts: hosts
+  - zone: host_zone
+  - host_name: host_name_body
+  - service: host_service
+
+**Example List Hosts**
 
 .. literalinclude:: ../../doc/api_samples/os-hosts/hosts-list-resp.json
    :language: javascript
@@ -59,7 +67,17 @@ Request
 Response
 --------
 
-**Example Show Host Details: JSON response**
+.. rest_parameters:: parameters.yaml
+
+  - host: host_resource_array
+  - resource: host_resource
+  - host.project: host_project
+  - host.cpu: host_cpu
+  - host.memory_mb: host_memory_mb
+  - host.disk_gb: host_disk_gb
+  - host.host: host_name_body
+
+**Example Show Host Details**
 
 .. literalinclude:: ../../doc/api_samples/os-hosts/host-get-resp.json
    :language: javascript
@@ -83,6 +101,8 @@ Request
 
   - tenant_id: tenant_id
   - host_name: host_name
+  - status: host_status_body_in
+  - maintenance_mode: host_maintenance_mode_in
 
 **Example Enable Host: JSON request**
 
@@ -92,7 +112,13 @@ Request
 Response
 --------
 
-**Example Enable Host: JSON response**
+.. rest_parameters:: parameters.yaml
+
+  - host: host_name_body
+  - status: host_status_body 
+  - maintenance_mode: host_maintenance_mode
+
+**Example Enable Host**
 
 .. literalinclude:: ../../doc/api_samples/os-hosts/host-put-maintenance-resp.json
    :language: javascript
@@ -120,6 +146,11 @@ Request
 Response
 --------
 
+.. rest_parameters:: parameters.yaml
+
+  - host: host_name_body
+  - power_action: host_power_action
+
 **Example Reboot Host: JSON response**
 
 .. literalinclude:: ../../doc/api_samples/os-hosts/host-get-reboot.json
@@ -148,7 +179,12 @@ Request
 Response
 --------
 
-**Example Shut Down Host: JSON response**
+.. rest_parameters:: parameters.yaml
+
+  - host: host_name_body
+  - power_action: host_power_action
+
+**Example Shut Down Host**
 
 .. literalinclude:: ../../doc/api_samples/os-hosts/host-get-shutdown.json
    :language: javascript
@@ -176,7 +212,12 @@ Request
 Response
 --------
 
-**Example Start Host: JSON response**
+.. rest_parameters:: parameters.yaml
+
+  - host: host_name_body
+  - power_action: host_power_action
+
+**Example Start Host**
 
 .. literalinclude:: ../../doc/api_samples/os-hosts/host-get-startup.json
    :language: javascript

api-ref/source/parameters.yaml

@@ -130,6 +130,18 @@ host_name:
   in: path
   required: true
   type: string
+host_status_body_in:
+  description: |
+    The status of the current host, either 'enabled' or 'disabled'.
+  in: path
+  required: false
+  type: string
+host_maintenance_mode_in:
+  description: |
+    Mode of maintenance state, either 'on_maintenance' or 'off_maintenance'
+  in: path
+  required: false
+  type: string
 hypervisor_id:
   description: |
     The UUID of the hypervisor.
@@ -1170,6 +1182,84 @@ host_status:
   in: body
   required: true
   type: string
+host_service:
+  description: |
+    The service name which is running on the host.
+  in: body
+  required: true
+  type: string
+host_resource_array:
+  description: |
+    The array that includes resource info of the host.
+  in: body
+  required: true
+  type: array
+host_resource:
+  description: |
+    The resource info of the host.
+  in: body
+  required: true
+  type: object
+host_project:
+  description: |
+    The project id (or special name like total, used_now, used_max).
+  in: body
+  required: true
+  type: string
+host_cpu:
+  description: |
+    The cpu info on the host.
+  in: body
+  required: true
+  type: string
+host_memory_mb:
+  description: |
+    The memory info on the host (in MB).
+  in: body
+  required: true
+  type: string
+host_disk_gb:
+  description: |
+    The disk info on the host (in GB).
+  in: body
+  required: true
+  type: string
+host_status_body:
+  description: |
+    The status of the current host, either 'enabled' or 'disabled'.
+  in: body
+  required: true
+  type: string
+host_maintenance_mode:
+  description: |
+    Mode of maintenance state, either 'on_maintenance' or 'off_maintenance'
+  in: body
+  required: true
+  type: string
+host_power_action:
+  description: |
+    The power action on the host.
+  in: body
+  required: true
+  type: string
+host_name_body:
+  description: |
+    The name of the host.
+  in: body
+  required: true
+  type: string
+host_zone:
+  description: |
+    The available zone of the host.
+  in: body
+  required: true
+  type: string
+hosts:
+  description: |
+    An array of host information
+  in: body
+  required: true
+  type: array
 hypervisor_type:
   in: body
   required: true