Fix problems left in api-ref

This patch fixes the known problems in api-ref docs:

- the patch update stack api is now documented;
- the patch update preview api is now documented;
- the unused parameters in 'parameters.yaml' are all removed;
- some incorrect references of parameters are fixed.

Change-Id: I89457c98f542304df788636e4ad3ace5d2e7deb5

api-ref/source/v1/parameters.yaml

@@ -326,7 +326,7 @@ tags_query:
   in: query
   required: false
   type: string
-template_type:
+template_type_query:
   description: |
     Specify the resource template type. The valid types are: ``cfn``, ``hot``.
   in: query
@@ -430,12 +430,6 @@ capabilities:
   in: body
   required: true
   type: array
-capabilities_1:
-  description: |
-    A list of stack capabilities.
-  in: body
-  required: true
-  type: array
 check:
   description: |
     Specify the ``check`` action in the request body.
@@ -463,28 +457,12 @@ config:
   in: body
   required: false
   type: string
-config_1:
-  description: |
-    The configuration code.
-  in: body
-  required: true
-  type: string
 config_id:
   description: |
     The UUID of the configuration.
   in: body
   required: true
   type: string
-config_id_3:
-  description: |
-    The UUID of the software configuration resource
-    to run when applying to the server. This UUID might not be the
-    same configuration UUID with which the deployment was created
-    because ephemeral configurations are created throughout the life
-    cycle of the deployment.
-  in: body
-  required: true
-  type: string
 config_name:
   description: |
     The name of the software configuration.
@@ -705,6 +683,20 @@ existing:
   required: false
   default: false
   type: boolean
+existing_patch:
+  description:
+    This parameter can be specified but it will be ignored. When using the
+    ``PATCH`` verb to update a stack,the orchestration service will try reuse
+    the existing stack template, parameters and environment. If ``template``
+    parameter is not provided, the existing template is used. If
+    ``template_files`` is not provided, the existing environment is used.
+    Parameters specified in the ``parameters`` key will patch over the
+    existing values in the current stack. Parameters omitted will keep the
+    existing values.
+  in: body
+  required: false
+  default: true
+  type: boolean
 files:
   description: |
     Supplies the contents of files referenced in the template or the
@@ -787,13 +779,6 @@ group:
   in: body
   required: false
   type: string
-group_1:
-  description: |
-    The name of the group in which the software is
-    configured.
-  in: body
-  required: true
-  type: string
 heat_template_version:
   description: |
     The version of the orchestration HOT template.
@@ -831,12 +816,6 @@ inputs:
   in: body
   required: false
   type: array
-inputs_1:
-  description: |
-    A list of inputs to configure the software.
-  in: body
-  required: true
-  type: array
 links:
   description: |
     A list of URLs for the stack. Each URL is a JSON object with an ``href``
@@ -871,24 +850,12 @@ metadata:
   in: body
   required: true
   type: object
-name_1:
-  description: |
-    The name of the configuration to create.
-  in: body
-  required: false
-  type: string
 notification_topics:
   description: |
     List of notification topics for stack.
   in: body
   required: true
   type: array
-notification_topics_1:
-  description: |
-    A list of stack notifications.
-  in: body
-  required: true
-  type: array
 options:
   description: |
     Map that contains options that are specific to
@@ -1035,12 +1002,6 @@ parameters:
   in: body
   required: false
   type: object
-parameters_show:
-  description: |
-    A map of parameters defined for the stack.
-  in: body
-  required: true
-  type: object
 parent:
   description: |
     The stack ID of the parent stack, if this is a nested stack.
@@ -1216,12 +1177,6 @@ Resources:
   in: body
   required: true
   type: object
-resources_2:
-  description: |
-    The snapshot resources.
-  in: body
-  required: true
-  type: object
 resources_abandon:
   description: |
     The required sources for creating the stack template.
@@ -1608,12 +1563,6 @@ type:
   in: body
   required: true
   type: string
-update_allowed:
-  description: |
-    If set to ``true``, update is allowed.
-  in: body
-  required: true
-  type: boolean
 update_show_nested:
   description: |
     Set to ``true`` to include nested stacks in the preview result.

api-ref/source/v1/resource-types.inc

@@ -104,7 +104,7 @@ Request Parameters
 
    - tenant_id: tenant_id
    - type_name: type_name
-   - template_type: template_type
+   - template_type: template_type_query
 
 Response Parameters
 -------------------

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

@@ -87,7 +87,7 @@ Reponse Parameters
 
    - X-Openstack-Request-Id: request_id
    - template_functions: template_functions
-   - description: template_description
+   - description: function_description
    - functions: functions
 
 Response Example

api-ref/source/v1/stacks.inc

@@ -124,7 +124,7 @@ Response Parameters
    - outputs: stack_outputs
    - parameters: stack_parameters
    - parent: parent
-   - resources: resources
+   - resources: stack_resources
    - stack: stack
    - stack_name: stack_name
    - stack_owner: stack_owner
@@ -398,6 +398,72 @@ Response Example
    :language: javascript
 
 
+Update stack (PATCH)
+====================
+
+.. rest_method::  PATCH /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
+
+Updates a stack using the ``PATCH`` verb. The logic is identical to stack
+update with a ``PUT`` verb except that the ``existing`` parameter is always
+set to True.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 404
+   - 500
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - stack_name: stack_name_url
+   - stack_id: stack_id_url
+   - clear_parameters: clear_parameters
+   - disable_rollback: disable_rollback
+   - environment: environment
+   - environment_files: environment_files
+   - existing: existing_patch
+   - files: files
+   - parameters: parameters
+   - tags: tags
+   - template: template
+   - template_url: template_url
+   - timeout_mins: timeout_mins
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - code: code
+   - message: message
+   - title: title
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-update-response.json
+   :language: javascript
+
+
 Preview stack update
 ====================
 
@@ -466,6 +532,76 @@ Response Example
    :language: javascript
 
 
+Preview stack update (PATCH)
+============================
+
+.. rest_method::  PATCH /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/preview
+
+Previews an update for a stack using the ``PATCH`` verb. The logic is the same
+as that of stack update preview with a ``PUT`` verb except that the
+``existing`` parameter is always set to True.
+
+Response Codes
+--------------
+
+.. 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
+   - stack_name: stack_name_url
+   - stack_id: stack_id_url
+   - clear_parameters: clear_parameters
+   - disable_rollback: disable_rollback
+   - environment: environment
+   - environment_files: environment_files
+   - existing: existing_patch
+   - files: files
+   - parameters: parameters
+   - show_nested: update_show_nested
+   - tags: tags
+   - template: template
+   - template_url: template_url
+   - timeout_mins: timeout_mins
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - resource_changes: resource_changes
+   - added: preview_added
+   - deleted: preview_deleted
+   - replaced: preview_replaced
+   - unchanged: preview_unchanged
+   - updated: preview_updated
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-update-preview-response.json
+   :language: javascript
+
+
 Find stack for deletion
 =======================
 
@@ -556,7 +692,8 @@ Abandon stack
 
 .. rest_method::  DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/abandon
 
-Deletes a stack but leaves its resources intact, and returns data that describes the stack and its resources.
+Deletes a stack but leaves its resources intact, and returns data that
+describes the stack and its resources.
 
 This is a preview feature which has to be explicitly enabled by setting the
 following option in the ``heat.conf`` file::