[api-ref] Rewrite the Heat API version

This patch validate the header: Change redundant request parameters to
response parameters and add more parameters to response parameters table.
http://developer.openstack.org/api-ref/orchestration/
v1/?expanded=list-versions-detail

Change-Id: I392af2faa54940f93ce1344e5e880a5583099608

api-ref/source/v1/parameters.yaml

@@ -1591,6 +1591,23 @@ updated_time:
   in: body
   required: true
   type: string
+version_id:
+  type: string
+  in: body
+  required: true
+  description: >
+    A common name for the version in question. Informative only, it
+    has no real semantic meaning.
+version_status:
+  type: string
+  in: body
+  required: true
+  description: |
+    The status of this API version. This can be one of:
+
+    - ``CURRENT``: this is the preferred version of the API to use
+    - ``SUPPORTED``: this is an older, but still supported version of the API
+    - ``DEPRECATED``: a deprecated version of the API that is slated for removal
 versions:
   description: |
     A list of all orchestration API versions. Each object in the list provides

api-ref/source/v1/versions.inc

@@ -23,13 +23,16 @@ Request Parameters
 
 This operation does not accept a request body.
 
-Request Parameters
+Response Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
    - X-Openstack-Request-Id: request_id
    - versions: versions
+   - id: version_id
+   - status: version_status
+   - links: links
 
 Response Example
 ----------------