api-ref - template version and functions

This patch fixes problems found in api-ref documentation about template
versions and template functions. The detailed changes include:

- Fixed status codes for the related APIs;
- Fixed response parameters which were missing in original doc;
- Fixed dcumentation about template-validate API where some request
  parameters were not documented.

Change-Id: I72d4a19e36f3bb3d139becd308ebcdf4103c2570

api-ref/source/v1/parameters.yaml

@@ -78,7 +78,7 @@ stack_name_url:
   in: path
   required: false
   type: string
-template_version:
+template_version_url:
   description: |
     The version of the heat template.
   in: path
@@ -602,7 +602,7 @@ deployment_updated_time:
   type: string
 Description:
   description: |
-    The description specified in the CFN template.
+    The description specified in the template.
   in: body
   required: true
   type: string
@@ -767,6 +767,18 @@ files:
   in: body
   required: false
   type: object
+function_description:
+  description: |
+    The textual description about the usage of the template function.
+  in: body
+  required: true
+  type: string
+functions:
+  description: |
+    The name of a function supported by the specified template version.
+  in: body
+  required: true
+  type: string
 group:
   description: |
     Namespace that groups this software configuration
@@ -936,8 +948,7 @@ parameter_defaults:
   type: object
 ParameterGroups:
   description: |
-    A list of parameter groups. Each group contains a
-    list of parameter names.
+    A list of parameter groups. Each group contains a list of parameter names.
   in: body
   required: false
   type: array
@@ -1509,6 +1520,12 @@ template_description:
   in: body
   required: true
   type: string
+template_functions:
+  descriptions: |
+    A list of template function descriptors.
+  in: body
+  required: true
+  type: array
 template_outputs:
   description: |
     Key and value pairs that contain output data.
@@ -1528,6 +1545,12 @@ template_resources:
   in: body
   required: true
   type: object
+template_type:
+  description: |
+    The type of the template version which can be ``cfn`` or ``hot``.
+  in: body
+  required: true
+  type: string
 template_url:
   description: |
     A URI to the location containing the stack template on which to perform
@@ -1538,6 +1561,22 @@ template_url:
   in: body
   required: false
   type: string
+template_version:
+  description: |
+    The version string of the template format.
+  in: body
+  required: true
+  type: string
+template_version_alias:
+  description: |
+    The alias of a template version. For newer template versions supported,
+    the orchestration service is moving away from template versioning using
+    release date (which is hard to remember). Newer versions are named after
+    the OpenStack release code name. For example,
+    ``heat_template_version.newton``.
+  in: body
+  required: true
+  type: list
 template_versions:
   description: |
     A list of template version object each describes the type name and version

api-ref/source/v1/samples/template-versions-response.json

@@ -1,32 +1,44 @@
 {
     "template_versions": [
         {
-            "version": "heat_template_version.2014-10-16",
-            "type": "hot"
-        },
-        {
-            "version": "heat_template_version.2015-04-30",
-            "type": "hot"
-        },
-        {
-            "version": "HeatTemplateFormatVersion.2012-12-12",
-            "type": "cfn"
-        },
-        {
-            "version": "heat_template_version.2015-10-15",
-            "type": "hot"
-        },
-        {
+            "alias": [],
             "version": "AWSTemplateFormatVersion.2010-09-09",
             "type": "cfn"
         },
         {
+            "alias": [],
+            "version": "HeatTemplateFormatVersion.2012-12-12",
+            "type": "cfn"
+        },
+        {
+            "alias": [],
             "version": "heat_template_version.2013-05-23",
             "type": "hot"
         },
         {
+            "alias": [],
+            "version": "heat_template_version.2014-10-16",
+            "type": "hot"
+        },
+        {
+            "alias": [],
+            "version": "heat_template_version.2015-04-30",
+            "type": "hot"
+        },
+        {
+            "alias": [],
+            "version": "heat_template_version.2015-10-15",
+            "type": "hot"
+        },
+        {
+            "alias": [],
             "version": "heat_template_version.2016-04-08",
             "type": "hot"
+        },
+        {
+            "alias": ["heat_template_version.newton"],
+            "version": "heat_template_version.2016-10-14",
+            "type": "hot"
         }
     ]
 }

api-ref/source/v1/stack-templates.inc

@@ -11,16 +11,39 @@ List template versions
 
 Lists all available template versions.
 
-Normal response codes: 200
-Error response codes:404,500,401,400,
+Response Codes
+--------------
 
-Request
--------
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 404
+   - 500
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: tenant_id
 
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request_id: request_id
+   - template_versions: template_versions
+   - alias: template_version_alias
+   - type: template_type
+   - version: template_version
+
+
 Response Example
 ----------------
 
@@ -35,18 +58,37 @@ List template functions
 
 Lists all available functions for a template version.
 
+Response Codes
+--------------
 
-Normal response codes: 200
-Error response codes:401,400,
+.. rest_status_code:: success status.yaml
 
+   - 200
 
-Request
--------
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 404
+   - 500
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: tenant_id
-   - template_version: template_version
+   - template_version: template_version_url
+
+Reponse Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - template_functions: template_functions
+   - description: template_description
+   - functions: functions
 
 Response Example
 ----------------
@@ -62,19 +104,31 @@ Validate template
 
 Validates a template.
 
-Normal response codes: 200
-Error response codes:
+Response Codes
+--------------
 
-Request
--------
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 500
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - environment: environment
-   - template_url: template_url
-   - template: template
    - tenant_id: tenant_id
+   - environment: environment
+   - environment_files: environment_files
+   - files: files
    - ignore_errors: ignore_errors
+   - show_nested: show_nested
+   - template: template
+   - template_url: template_url
 
 Request Example
 ---------------
@@ -87,8 +141,9 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - ParameterGroups: ParameterGroups
+   - X-Openstack-Request-Id: request_id
    - Description: Description
+   - ParameterGroups: ParameterGroups
    - Parameters: Parameters
 
 Response Example