Fix the parameters for os-agents API

* Add notes for API bug: update return string type's agent id
* Fix the parameters for create agent
* Fix the description of agent id in the update url.

Part of bp:api-ref-in-rst

Change-Id: I5c102ef8a08123089ec4a85dde5716eda12fb8c7

api-ref/source/os-agents.inc

@@ -29,7 +29,7 @@ Request
 .. rest_parameters:: parameters.yaml
 
   - tenant_id: tenant_id
-  - hypervisor: OS-EXT-SRV-ATTR:hypervisor_hostname
+  - hypervisor: hypervisor
   - architecture: architecture
   - os: os
   - url: url
@@ -44,6 +44,16 @@ Request
 Response
 --------
 
+.. rest_parameters:: parameters.yaml
+
+  - hypervisor: hypervisor
+  - architecture: architecture
+  - os: os
+  - url: url
+  - md5hash: md5hash
+  - version: version
+  - agent_id: agent_id
+
 **Example Create Agent Build: JSON response**
 
 .. literalinclude:: ../../doc/api_samples/os-agents/agent-post-resp.json
@@ -137,7 +147,7 @@ Response
 
 .. rest_parameters:: parameters.yaml
 
-  - agent_id: agent_id
+  - agent_id: agent_id_str
   - url: url
   - md5hash: md5hash
   - version: version

api-ref/source/parameters.yaml

@@ -24,7 +24,7 @@ admin_tenant_id:
   type: string
 agent_build_id:
   description: |
-    The UUID of the agent build.
+    The id of the agent build.
   in: path
   required: true
   type: string
@@ -667,6 +667,13 @@ agent_id:
   in: body
   required: true
   type: integer
+agent_id_str:
+  description: |
+    The agent ID. (This is a bug of API, this should be integer type which is consistent with
+    the responses of agent create and list. This will be fixed in later microversion.)
+  in: body
+  required: true
+  type: string
 alias:
   description: |
     A short name by which this extension is also known.