Fix api-ref doc for software deployment.

The current api documentation for software deployment is a mess. This
patch is an attempt to fix it.

Change-Id: I41da79865c2836e6750314497e910982bc5462a9

2 files changed, 202 insertions, 234 deletions

diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml
index a9f0900ab..052c11e58 100644
--- a/api-ref/source/v1/parameters.yaml
+++ b/api-ref/source/v1/parameters.yaml
@@ -1,18 +1,25 @@
 # variables in header
 
 # variables in path
-config_id:
+config_id_url:
   description: |
     The UUID of the configuration.
   in: path
   required: false
   type: string
-deployment_id:
+deployment_id_url:
   description: |
     The UUID of the deployment.
   in: path
   required: false
   type: string
+deployment_server_id_url:
+  description: |
+    The UUID of the server for which to fetch
+    server configuration metadata.
+  in: path
+  required: true
+  type: string
 event_id:
   description: |
     The UUID of the event that is related to the
@@ -32,13 +39,6 @@ resource_name:
   in: path
   required: false
   type: string
-server_id_2:
-  description: |
-    The UUID of the server for which to fetch
-    configuration metadata.
-  in: path
-  required: false
-  type: string
 snapshot_id:
   description: |
     The UUID of the snapshot.
@@ -57,6 +57,12 @@ stack_name:
   in: path
   required: false
   type: string
+template_version:
+  description: |
+    The version of the heat template.
+  in: path
+  required: true
+  type: string
 tenant_id:
   description: |
     The UUID of the tenant. A tenant is also known as
@@ -70,12 +76,6 @@ type_name:
   in: path
   required: false
   type: string
-template_version:
-  description: |
-    The version of the heat template.
-  in: path
-  required: true
-  type: string
 
 # variables in query
 action_3:
@@ -85,6 +85,12 @@ action_3:
   in: query
   required: false
   type: string
+deployment_server_id_query:
+  description: |
+    The UUID of the target server.
+  in: query
+  required: false
+  type: string
 global_tenant:
   description: |
     Set to ``true`` to include stacks from all
@@ -100,6 +106,14 @@ id_4:
   in: query
   required: false
   type: string
+ignore_errors:
+  description: |
+    List of comma separated error codes to ignore.
+# TODO(kanagaraj-manickam) add the cross reference to the API to retrieve the
+# list of error code supported, once its made available in heat.
+  in: query
+  required: false
+  type: string
 limit:
   description: |
     Requests a page size of items. Returns a number
@@ -299,21 +313,19 @@ with_count:
   in: query
   required: false
   type: boolean
-with_detail:
+with_description:
   description: |
-    Enables detailed resource information for each
-    resource in list of resources.
+    Either display resource type's description or not. Default is ``false``
   in: query
   required: false
   type: boolean
-ignore_errors:
+with_detail:
   description: |
-    List of comma separated error codes to ignore.
-# TODO(kanagaraj-manickam) add the cross reference to the API to retrieve the
-# list of error code supported, once its made available in heat.
+    Enables detailed resource information for each
+    resource in list of resources.
   in: query
   required: false
-  type: string
+  type: boolean
 
 # variables in body
 Description:
@@ -361,26 +373,6 @@ Resources:
   in: body
   required: true
   type: object
-action:
-  description: |
-    The current stack action that triggers this
-    deployment resource.
-  in: body
-  required: true
-  type: string
-action_1:
-  description: |
-    The deployment action.
-  in: body
-  required: true
-  type: string
-action_2:
-  description: |
-    Current stack action in which this deployment
-    resource is being triggered.
-  in: body
-  required: true
-  type: string
 adopt_stack_data:
   description: |
     Existing resources data to adopt a stack. Data
@@ -440,14 +432,7 @@ config_1:
   in: body
   required: true
   type: string
-config_id_1:
-  description: |
-    The UUID of the software configuration resource
-    that runs when applying to the server.
-  in: body
-  required: true
-  type: string
-config_id_2:
+config_id:
   description: |
     The UUID of the configuration.
   in: body
@@ -463,6 +448,12 @@ config_id_3:
   in: body
   required: true
   type: string
+config_name:
+  description: |
+    The name of the software configuration.
+  in: body
+  required: true
+  type: string
 created_at:
   description: |
     The date and time when the resource was created.
@@ -613,6 +604,72 @@ deleted_at:
   in: body
   required: true
   type: string
+deployment_action:
+  description: |
+    The stack action that triggers this deployment resource.
+  in: body
+  required: false
+  type: string
+deployment_config_id:
+  description: |
+    The UUID of the software configuration resource
+    that runs when applying to the server.
+  in: body
+  required: true
+  type: string
+deployment_id:
+  description: |
+    The UUID of the software deployment.
+  in: body
+  required: true
+  type: string
+deployment_metadata:
+  description: |
+    The metadata about a software deployment.
+  in: body
+  required: true
+  type: array
+deployment_output_values:
+  description: |
+    A dict comprised of the output data from a software deployment.
+  in: body
+  required: true
+  type: object
+deployment_status:
+  description: |
+    Current status of the deployment. A valid value
+    is ``COMPLETE``, ``IN_PROGRESS``, or ``FAILED``.
+  in: body
+  required: false
+  type: string
+deployment_status_reason:
+  description: |
+    The reason for the current deployment status.
+  in: body
+  required: false
+  type: string
+
+deployment_updated_time:
+  description: |
+    The date and time when the software deployment was updated.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+
+    If the ``updated_at`` date and time stamp is not set, its value is
+    ``null``.
+  in: body
+  required: false 
+  type: string
 description:
   description: |
     The description of the stack resource.
@@ -683,6 +740,12 @@ disable_rollback_2:
   in: body
   required: true
   type: boolean
+engine_id:
+  description: |
+    The ID of engine service.
+  in: body
+  required: true
+  type: string
 environment:
   description: |
     A JSON environment for the stack.
@@ -772,21 +835,15 @@ heat_template_version:
   in: body
   required: true
   type: string
-hostname:
-  description: |
-    The name of the host for the service.
-  in: body
-  required: true
-  type: string
 host:
   description: |
     The host for the service.
   in: body
   required: true
   type: string
-engine_id:
+hostname:
   description: |
-    The ID of engine service.
+    The name of the host for the service.
   in: body
   required: true
   type: string
@@ -796,18 +853,6 @@ id:
   in: body
   required: true
   type: string
-id_1:
-  description: |
-    The UUID of the software deployment.
-  in: body
-  required: true
-  type: string
-id_2:
-  description: |
-    The UUID of the system-assigned stack.
-  in: body
-  required: true
-  type: string
 id_3:
   description: |
     The UUID of the snapshot.
@@ -822,10 +867,10 @@ id_5:
   type: string
 input_values:
   description: |
-    A list of input data.
+    A dict comprises of input data as key-value pairs.
   in: body
-  required: true
-  type: array
+  required: false
+  type: object
 inputs:
   description: |
     Schema that represents the inputs that this
@@ -867,12 +912,6 @@ name_1:
   in: body
   required: false
   type: string
-name_2:
-  description: |
-    The name of the software configuration.
-  in: body
-  required: true
-  type: string
 name_3:
   description: |
     The name of the snapshot.
@@ -898,13 +937,6 @@ options:
   in: body
   required: false
   type: string
-options_1:
-  description: |
-    The options, if any, to include in the code. For
-    example any dependent flags.
-  in: body
-  required: true
-  type: string
 output_error:
   description: |
     The error in a stack output.
@@ -923,18 +955,12 @@ output_value:
   in: body
   required: true
   type: string
-output_values:
-  description: |
-    A list of output data.
-  in: body
-  required: true
-  type: array
 output_values_1:
   description: |
     Map of output values for the deployment, as
     signaled from the server.
   in: body
-  required: false
+  required: 
   type: object
 outputs:
   description: |
@@ -1153,6 +1179,12 @@ resource:
   in: body
   required: true
   type: object
+resource_description:
+  description: |
+    Displays resource type's description.
+  in: body
+  required: false
+  type: string
 resource_name_1:
   description: |
     The name of the resource.
@@ -1216,12 +1248,6 @@ server_id:
   in: body
   required: true
   type: string
-server_id_1:
-  description: |
-    The UUID of the server.
-  in: body
-  required: true
-  type: string
 services:
   description: |
     A list of heat engines.
@@ -1350,27 +1376,6 @@ status:
   in: body
   required: true
   type: string
-status_1:
-  description: |
-    Current status of the deployment. A valid value
-    is ``COMPLETE``, ``IN_PROGRESS``, or ``FAILED``.
-  in: body
-  required: false
-  type: string
-status_2:
-  description: |
-    The status of the software deployment. The value
-    is ``INPROGRESS`` or ``COMPLETE``.
-  in: body
-  required: true
-  type: string
-status_3:
-  description: |
-    Current status of the deployment. Value is
-    ``IN_PROGRESS``, ``COMPLETE``, or ``FAILED``.
-  in: body
-  required: false
-  type: string
 status_4:
   description: |
     The status of the snapshot.
@@ -1384,12 +1389,6 @@ status_reason:
   in: body
   required: false
   type: string
-status_reason_1:
-  description: |
-    The debug information for the current status.
-  in: body
-  required: true
-  type: string
 status_reason_2:
   description: |
     The reason for the current snapshot status.
@@ -1592,44 +1591,3 @@ updated_time_1:
   in: body
   required: true
   type: string
-updated_time_2:
-  description: |
-    Time of last stack update in the following
-    format: ``YYYY-MM- DDThh:mm:ssTZD``, where ``TZD`` is the time
-    zone designator.
-  in: body
-  required: true
-  type: string
-updated_time_3:
-  description: |
-    The date and time when the stack was updated.
-
-    The date and time stamp format is `ISO 8601
-    <https://en.wikipedia.org/wiki/ISO_8601>`_:
-
-    ::
-
-       CCYY-MM-DDThh:mm:ss±hh:mm
-
-    For example, ``2015-08-27T09:49:58-05:00``.
-
-    The ``±hh:mm`` value, if included, is the time zone as an offset
-    from UTC.
-
-    If the ``updated_at`` date and time stamp is not set, its value is
-    ``null``.
-  in: body
-  required: true
-  type: string
-with_description:
-  description: |
-    Either display resource type's description or not. Default is ``false``
-  in: query
-  required: false
-  type: boolean
-resource_description:
-  description: |
-    Displays resource type's description.
-  in: body
-  required: false
-  type: string
diff --git a/api-ref/source/v1/software-config.inc b/api-ref/source/v1/software-config.inc
index 4e69ca095..9c4f990f1 100644
--- a/api-ref/source/v1/software-config.inc
+++ b/api-ref/source/v1/software-config.inc
@@ -22,7 +22,7 @@ Request Parameters
 
    - inputs: inputs
    - group: group
-   - name: name
+   - name: config_name
    - outputs: outputs
    - config: config
    - options: options
@@ -39,12 +39,13 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - id: config_id_2
+   - id: config_id
    - inputs: inputs
    - group: group
-   - name: name
+   - name: config_name
    - outputs: outputs
    - creation_time: creation_time
+   - updated_time: updated_time
    - config: config
    - options: options
    - software_config: software_config
@@ -81,10 +82,10 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - group: group
-   - name: name
    - creation_time: creation_time
-   - id: config_id_2
+   - group: group
+   - id: config_id
+   - name: config_name
    - software_configs: software_configs
 
 Response Example
@@ -119,14 +120,14 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - id: config_id_2
-   - inputs: inputs
-   - group: group
-   - name: name
-   - outputs: outputs
-   - creation_time: creation_time
    - config: config
+   - creation_time: creation_time
+   - group: group
+   - id: config_id
+   - inputs: inputs
+   - name: config_name
    - options: options
+   - outputs: outputs
    - software_config: software_config
 
 
@@ -152,7 +153,7 @@ Request Parameters
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: tenant_id
-   - config_id: config_id
+   - config_id: config_id_url
 
 
 Create deployment
@@ -162,7 +163,6 @@ Create deployment
 
 Creates a software deployment.
 
-
 Normal response codes: 200
 
 Error response codes:
@@ -172,12 +172,13 @@ Request Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - status: status
+   - action: deployment_action
+   - config_id: deployment_config_id
+   - input_values: input_values
    - server_id: server_id
-   - config_id: config_id
    - stack_user_project_id: stack_user_project_id
-   - action: action
-   - status_reason: status_reason
+   - status: deployment_status
+   - status_reason: deployment_status_reason
    - tenant_id: tenant_id
 
 Request Example
@@ -191,18 +192,17 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - status: status
-   - server_id: server_id
-   - config_id: config_id
-   - output_values: output_values
+   - action: deployment_action
+   - config_id: deployment_config_id
    - creation_time: creation_time
-   - updated_at: updated_at
+   - id: deployment_id
    - input_values: input_values
-   - action: action
-   - status_reason: status_reason
-   - id: id
+   - output_values: deployment_output_values
+   - server_id: server_id
    - software_deployment: software_deployment
-
+   - status: deployment_status
+   - status_reason: status_reason
+   - updated_time: deployment_updated_time
 
 Response Example
 ----------------
@@ -227,6 +227,7 @@ Request Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - server_id: deployment_server_id_query
    - tenant_id: tenant_id
 
 Response Parameters
@@ -234,16 +235,17 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - status: status
-   - server_id: server_id
-   - config_id: config_id
-   - output_values: output_values
+   - action: deployment_action
+   - config_id: deployment_config_id
    - creation_time: creation_time
-   - updated_at: updated_at
+   - id: deployment_id
    - input_values: input_values
-   - action: action
+   - output_values: deployment_output_values
+   - server_id: server_id
+   - software_deployments: software_deployments
+   - status: deployment_status
    - status_reason: status_reason
-   - id: id_2
+   - updated_time: deployment_updated_time
 
 Response Example
 ----------------
@@ -251,7 +253,6 @@ Response Example
 .. literalinclude:: samples/deployments-list-response.json
    :language: javascript
 
-
 Show deployment details
 =======================
 
@@ -259,7 +260,6 @@ Show deployment details
 
 Shows details for a software deployment.
 
-
 Normal response codes: 200
 
 Error response codes:
@@ -269,26 +269,25 @@ Request Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - deployment_id: deployment_id_url
    - tenant_id: tenant_id
-   - deployment_id: deployment_id
-
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - status: status
-   - server_id: server_id
-   - config_id: config_id
-   - output_values: output_values
+   - action: deployment_action
+   - config_id: deployment_config_id
    - creation_time: creation_time
-   - updated_at: updated_at
+   - id: deployment_id
    - input_values: input_values
-   - action: action
-   - status_reason: status_reason
-   - id: id_2
+   - output_values: deployment_output_values
+   - server_id: server_id
    - software_deployment: software_deployment
+   - status: deployment_status
+   - status_reason: status_reason
+   - updated_time: deployment_updated_time
 
 Response Example
 ----------------
@@ -296,7 +295,6 @@ Response Example
 .. literalinclude:: samples/deployment-show-response.json
    :language: javascript
 
-
 Update deployment
 =================
 
@@ -304,7 +302,6 @@ Update deployment
 
 Updates a software deployment.
 
-
 Normal response codes: 200
 
 Error response codes:
@@ -314,13 +311,14 @@ Request Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - action: action
-   - output_values: output_values
-   - config_id: config_id
-   - status: status
+   - action: deployment_action
+   - config_id: deployment_config_id
+   - deployment_id: deployment_id_url
+   - input_values: input_values
+   - output_values: deployment_output_values
+   - status: deployment_status
    - status_reason: status_reason
    - tenant_id: tenant_id
-   - deployment_id: deployment_id
 
 Request Example
 ---------------
@@ -333,17 +331,17 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - status: status
-   - server_id: server_id
-   - config_id: config_id
-   - output_values: output_values
+   - action: deployment_action
+   - config_id: deployment_config_id
    - creation_time: creation_time
-   - updated_at: updated_at
+   - id: deployment_id
    - input_values: input_values
-   - action: action
+   - output_values: deployment_output_values
+   - server_id: server_id
+   - software_deployments: software_deployments
+   - status: deployment_status
    - status_reason: status_reason
-   - id: id
-   - software_deployment: software_deployment
+   - updated_time: deployment_updated_time
 
 Response Example
 ----------------
@@ -351,7 +349,6 @@ Response Example
 .. literalinclude:: samples/deployment-update-response.json
    :language: javascript
 
-
 Delete deployment
 =================
 
@@ -366,9 +363,8 @@ Request Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - deployment_id: deployment_id_url
    - tenant_id: tenant_id
-   - deployment_id: deployment_id
-
 
 Show server configuration metadata
 ==================================
@@ -380,7 +376,6 @@ Shows the deployment configuration metadata for a server.
 Use the ``group`` property to specify the configuration hook to
 which the pass the metadata item.
 
-
 Normal response codes: 200
 
 Error response codes:
@@ -390,9 +385,24 @@ Request Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - server_id: server_id
+   - server_id: deployment_server_id_url
    - tenant_id: tenant_id
 
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - config: config
+   - creation_time: creation_time
+   - group: group
+   - id: config_id
+   - inputs: inputs
+   - metadata: deployment_metadata
+   - name: config_name
+   - options: options
+   - outputs: outputs
+   - updated_time: updated_time
 
 Response Example
 ----------------