Api-ref: fix v2/v3 hosts extension api doc

Supplement error response codes and fix parameters problem.

Change-Id: Ia24c6980f437ab6838d64c345bc9c10a100762e1
Closes-Bug: #1715286

api-ref/source/v2/hosts.inc

@@ -1,7 +1,7 @@
 .. -*- rst -*-
 
 Hosts extension (os-hosts)
-====================================
+==========================
 
 Administrators only, depending on policy settings.
 
@@ -9,7 +9,7 @@ Lists, shows hosts.
 
 
 List all hosts
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~
 
 .. rest_method::  GET /v2/{admin_tenant_id}/os-hosts
 
@@ -17,6 +17,8 @@ Lists all hosts summary info that is not disabled.
 
 Normal response codes: 200
 
+Error response codes: badRequest(400), unauthorized(401), forbidden(403)
+
 Request
 -------
 
@@ -34,7 +36,7 @@ Response Parameters
    - service: host_service
    - zone: availability_zone_3
    - service-state: service_state
-   - host_name: hostname
+   - host_name: host_name_1
    - last-update: updated_at
 
 Response Example
@@ -56,7 +58,7 @@ cinder-volume service has been disabled.
 
 Normal response codes: 200
 
-Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
+Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
 
 Request
 -------
@@ -74,8 +76,8 @@ Response
   - volume_count: total_count
   - total_volume_gb: totalGigabytesUsed
   - total_snapshot_gb: totalSnapshotsUsed
-  - project: admin_tenant_id
-  - host: host
+  - project: project_id_2
+  - host: host_name_1
   - snapshot_count: totalSnapshotsUsed
 
 **Example Show Host Details**

api-ref/source/v2/parameters.yaml

@@ -678,6 +678,12 @@ host_name:
   in: body
   required: false
   type: string
+host_name_1:
+  description: |
+    The name of the host that hosts the storage backend.
+  in: body
+  required: true
+  type: string
 host_service:
   description: |
     The name of the service which is running on the host.
@@ -1343,6 +1349,13 @@ project_id_1:
   in: body
   required: true
   type: string
+project_id_2:
+  description: |
+    The UUID of the project which the host resource belongs to.
+    In the summary resource, the value is ``(total)``.
+  in: body
+  required: true
+  type: string
 properties:
   description: |
     The backend volume capabilities list, which is
@@ -1475,13 +1488,13 @@ security_groups:
   type: integer
 service_state:
   description: |
-    The state of the service. One of ``available`` or ``unavailable``.
+    The state of the service. One of ``enabled`` or ``disabled``.
   in: body
   required: true
   type: string
 service_status:
   description: |
-    The status of the service. One of ``enabled`` or ``disabled``.
+    The status of the service. One of ``available`` or ``unavailable``.
   in: body
   required: true
   type: string

api-ref/source/v3/hosts.inc

@@ -1,7 +1,7 @@
 .. -*- rst -*-
 
 Hosts extension (os-hosts)
-====================================
+==========================
 
 Administrators only, depending on policy settings.
 
@@ -17,6 +17,8 @@ Lists all hosts summary info that is not disabled.
 
 Normal response codes: 200
 
+Error response codes: badRequest(400), unauthorized(401), forbidden(403)
+
 Request
 -------
 
@@ -35,7 +37,7 @@ Response Parameters
    - service: host_service
    - zone: availability_zone_3
    - service-state: service_state
-   - host_name: hostname
+   - host_name: host_name_1
    - last-update: updated_at
 
 Response Example
@@ -57,7 +59,7 @@ cinder-volume service has been disabled.
 
 Normal response codes: 200
 
-Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
+Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
 
 Request
 -------
@@ -76,8 +78,8 @@ Response
   - volume_count: total_count
   - total_volume_gb: totalGigabytesUsed
   - total_snapshot_gb: totalSnapshotsUsed
-  - project: admin_project_id
-  - host: host
+  - project: project_id_2
+  - host: host_name_1
   - snapshot_count: totalSnapshotsUsed
 
 Response Example

api-ref/source/v3/parameters.yaml

@@ -1212,6 +1212,12 @@ host_name:
   in: body
   required: false
   type: string
+host_name_1:
+  description: |
+    The name of the host that hosts the storage backend.
+  in: body
+  required: true
+  type: string
 host_name_body:
   description: |
     The name of the host.
@@ -2029,6 +2035,13 @@ project_id_1:
   in: body
   required: true
   type: string
+project_id_2:
+  description: |
+    The Project ID which the host resource belongs to.
+    In the summary resource, the value is ``(total)``.
+  in: body
+  required: true
+  type: string
 properties:
   description: |
     The backend volume capabilities list, which is
@@ -2262,7 +2275,7 @@ service_key:
   type: string
 service_state:
   description: |
-    The state of the service. One of ``available`` or ``unavailable``.
+    The state of the service. One of ``enabled`` or ``disabled``.
   in: body
   required: true
   type: string
@@ -2274,7 +2287,7 @@ service_state_1:
   type: string
 service_status:
   description: |
-    The status of the service. One of ``enabled`` or ``disabled``.
+    The status of the service. One of ``available`` or ``unavailable``.
   in: body
   required: true
   type: string