api-ref - stack snapshots

This patch fixes problems in api-ref doc for stack snapshots releated
APIs. The specific changes include:

- Added response parameter/example for stack-restore API;
- Renamed stack-show-snapshot-response to stack-snapshot-show-response
  for consistency.
- Fixed parameter reference for software-config related to status
  and status_reason.
- Added missing docs for response codes.
- Removed some parameters which never appears in snapshot list calls;
- Reordered docs about API calls so the flow becomes: create, list,
  show, restore and delete.

Change-Id: Iff5d671da597f640eb59d28e1533e3f6506f622c

5 files changed, 175 insertions, 77 deletions

diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml
index 2d72a32d9..33f4714c2 100644
--- a/api-ref/source/v1/parameters.yaml
+++ b/api-ref/source/v1/parameters.yaml
@@ -508,12 +508,6 @@ creation_time:
   in: body
   required: true
   type: string
-data:
-  description: |
-    The snapshot data.
-  in: body
-  required: true
-  type: object
 deleted_at:
   description: |
     The date and time when the service engine was deleted.
@@ -1121,7 +1115,7 @@ resource_types_simple:
   in: body
   required: true
   type: array
-resource_upudate_status_reason:
+resource_update_status_reason:
   description: |
     The reason for the current stack resource state.
   in: body
@@ -1158,6 +1152,24 @@ resources_list:
   in: body
   required: true
   type: array
+restore_code:
+  description: |
+    HTTP status code for a restore request. Usually ``202 Accepted``.
+  in: body
+  required: true
+  type: string
+restore_message:
+  description: |
+    The message in the response to a stack restore request.
+  in: body
+  required: true
+  type: string
+restore_title:
+  description: |
+    The title of the response to a stack restore request. e.g. ``Accepted``.
+  in: body
+  required: true
+  type: string
 resume:
   description: |
     Specify the ``resume`` action in the request
@@ -1184,6 +1196,12 @@ snapshot:
   in: body
   required: true
   type: object
+snapshot_data:
+  description: |
+    The snapshot data.
+  in: body
+  required: true
+  type: object
 snapshot_id:
   description: |
     The UUID of the snapshot.
@@ -1202,6 +1220,12 @@ snapshot_status:
   in: body
   required: true
   type: string
+snapshot_status_reason:
+  description: |
+    The reason for the current snapshot status.
+  in: body
+  required: true
+  type: string
 snapshots:
   description: |
     A list of snapshots and their properties.
@@ -1367,19 +1391,6 @@ stacks:
   in: body
   required: true
   type: array
-status_reason:
-  description: |
-    Error description for the last status change,
-    which is ``FAILED`` status.
-  in: body
-  required: false
-  type: string
-status_reason_2:
-  description: |
-    The reason for the current snapshot status.
-  in: body
-  required: true
-  type: string
 support_status:
   description: |
     Information about the current support status of a resource type.
diff --git a/api-ref/source/v1/samples/stack-snapshot-restore-response.json b/api-ref/source/v1/samples/stack-snapshot-restore-response.json
new file mode 100644
index 000000000..f0a7a9259
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-snapshot-restore-response.json
@@ -0,0 +1,5 @@
+{
+    "code": "202 Accepted",
+    "message": "The request is accepted for processing.<br /><br />\n\n\n",
+    "title": "Accepted"
+}
diff --git a/api-ref/source/v1/samples/stack-show-snapshot-response.json b/api-ref/source/v1/samples/stack-snapshot-show-response.json
index 6646b9fb2..6646b9fb2 100644
--- a/api-ref/source/v1/samples/stack-show-snapshot-response.json
+++ b/api-ref/source/v1/samples/stack-snapshot-show-response.json
diff --git a/api-ref/source/v1/software-config.inc b/api-ref/source/v1/software-config.inc
index 9c4f990f1..8ecf33c92 100644
--- a/api-ref/source/v1/software-config.inc
+++ b/api-ref/source/v1/software-config.inc
@@ -172,6 +172,7 @@ Request Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - tenant_id: tenant_id
    - action: deployment_action
    - config_id: deployment_config_id
    - input_values: input_values
@@ -179,7 +180,6 @@ Request Parameters
    - stack_user_project_id: stack_user_project_id
    - status: deployment_status
    - status_reason: deployment_status_reason
-   - tenant_id: tenant_id
 
 Request Example
 ---------------
@@ -201,7 +201,7 @@ Response Parameters
    - server_id: server_id
    - software_deployment: software_deployment
    - status: deployment_status
-   - status_reason: status_reason
+   - status_reason: deployment_status_reason
    - updated_time: deployment_updated_time
 
 Response Example
@@ -227,8 +227,8 @@ Request Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - server_id: deployment_server_id_query
    - tenant_id: tenant_id
+   - server_id: deployment_server_id_query
 
 Response Parameters
 -------------------
@@ -244,7 +244,7 @@ Response Parameters
    - server_id: server_id
    - software_deployments: software_deployments
    - status: deployment_status
-   - status_reason: status_reason
+   - status_reason: deployment_status_reason
    - updated_time: deployment_updated_time
 
 Response Example
@@ -253,6 +253,7 @@ Response Example
 .. literalinclude:: samples/deployments-list-response.json
    :language: javascript
 
+
 Show deployment details
 =======================
 
@@ -269,8 +270,8 @@ Request Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - deployment_id: deployment_id_url
    - tenant_id: tenant_id
+   - deployment_id: deployment_id_url
 
 Response Parameters
 -------------------
@@ -286,7 +287,7 @@ Response Parameters
    - server_id: server_id
    - software_deployment: software_deployment
    - status: deployment_status
-   - status_reason: status_reason
+   - status_reason: deployment_status_reason
    - updated_time: deployment_updated_time
 
 Response Example
@@ -295,6 +296,7 @@ Response Example
 .. literalinclude:: samples/deployment-show-response.json
    :language: javascript
 
+
 Update deployment
 =================
 
@@ -311,14 +313,14 @@ Request Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - tenant_id: tenant_id
+   - deployment_id: deployment_id_url
    - 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
+   - status_reason: deployment_status_reason
 
 Request Example
 ---------------
@@ -340,7 +342,7 @@ Response Parameters
    - server_id: server_id
    - software_deployments: software_deployments
    - status: deployment_status
-   - status_reason: status_reason
+   - status_reason: deployment_status_reason
    - updated_time: deployment_updated_time
 
 Response Example
diff --git a/api-ref/source/v1/stack-snapshots.inc b/api-ref/source/v1/stack-snapshots.inc
index 85e6e0cc7..cf531c266 100644
--- a/api-ref/source/v1/stack-snapshots.inc
+++ b/api-ref/source/v1/stack-snapshots.inc
@@ -9,10 +9,22 @@ Snapshot a stack
 
 .. rest_method::  POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots
 
-Takes a snapshot of all resources in a stack. All snapshots are deleted when the stack is deleted.
+Takes a snapshot of all resources in a stack. All snapshots are deleted when
+the stack is deleted.
 
-Normal response codes: 200
-Error response codes:
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 404
+   - 500
 
 Request Parameters
 ------------------
@@ -35,12 +47,13 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - status: snapshot_status
-   - name: snapshot_name
-   - status_reason: status_reason
+   - X-Openstack-Request-Id: request_id
    - creation_time: creation_time
-   - data: data
+   - data: snapshot_data
    - id: snapshot_id
+   - name: snapshot_name
+   - status: snapshot_status
+   - status_reason: snapshot_status_reason
 
 Response Example
 ----------------
@@ -49,16 +62,24 @@ Response Example
    :language: javascript
 
 
-Show snapshot
-=============
+List snapshots
+==============
 
-.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots
 
-Shows details for a snapshot.
+Lists snapshots for a stack.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
 
+   - 200
 
-Normal response codes: 200
-Error response codes:
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 404
 
 Request Parameters
 ------------------
@@ -68,39 +89,46 @@ Request Parameters
    - tenant_id: tenant_id
    - stack_name: stack_name_url
    - stack_id: stack_id_url
-   - snapshot_id: snapshot_id_url
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - status: snapshot_status
-   - name: snapshot_name
-   - status_reason: status_reason
+   - X-Openstack-Request-Id: request_id
+   - snapshots: snapshots
    - creation_time: creation_time
-   - snapshot: snapshot
-   - template: template
-   - project_id: project_id
-   - data: data
+   - data: snapshot_data
    - id: snapshot_id
-   - resources: resources
+   - name: snapshot_name
+   - status: snapshot_status
+   - status_reason: snapshot_status_reason
 
 Response Example
 ----------------
 
-.. literalinclude:: samples/stack-show-snapshot-response.json
+.. literalinclude:: samples/stack-snapshots-list-response.json
    :language: javascript
 
-List snapshots
-==============
 
-.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots
+Show snapshot
+=============
 
-Lists snapshots for a stack.
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}
 
-Normal response codes: 200
-Error response codes:
+Shows details for a snapshot.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 404
 
 Request Parameters
 ------------------
@@ -110,35 +138,50 @@ Request Parameters
    - tenant_id: tenant_id
    - stack_name: stack_name_url
    - stack_id: stack_id_url
+   - snapshot_id: snapshot_id_url
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - status: snapshot_status
-   - name: snapshot_name
-   - status_reason: status_reason
+   - X-Openstack-Request-Id: request_id
+   - snapshot: snapshot
    - creation_time: creation_time
-   - snapshots: snapshots
-   - data: data
+   - data: snapshot_data
    - id: snapshot_id
+   - name: snapshot_name
+   - status: snapshot_status
+   - status_reason: snapshot_status_reason
 
 Response Example
 ----------------
 
-.. literalinclude:: samples/stack-snapshots-list-response.json
+.. literalinclude:: samples/stack-snapshot-show-response.json
    :language: javascript
 
 
-Delete snapshot
-===============
+Restore snapshot
+================
 
-.. rest_method::  DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}
+.. rest_method::  POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}/restore
 
-Deletes a stack snapshot.
+Restores a stack snapshot.
+
+You can restore only active stacks from a snapshot. You must recreate deleted
+stacks.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
 
-Error response codes:204,
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 404
 
 Request Parameters
 ------------------
@@ -150,17 +193,42 @@ Request Parameters
    - stack_id: stack_id_url
    - snapshot_id: snapshot_id_url
 
-Restore snapshot
-================
+Response Parameters
+-------------------
 
-.. rest_method::  POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}/restore
+.. rest_parameters:: parameters.yaml
 
-Restores a stack snapshot.
+   - X-Openstack-Request-Id: request_id
+   - code: restore_code
+   - message: restore_message
+   - title: restore_title
 
-You can restore only active stacks from a snapshot. You must
-recreate deleted stacks.
+Response Example
+----------------
 
-Error response codes:202,
+.. literalinclude:: samples/stack-snapshot-restore-response.json
+   :language: javascript
+
+
+Delete a snapshot
+=================
+
+.. rest_method::  DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}
+
+Deletes a stack snapshot.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 404
+   - 500
 
 Request Parameters
 ------------------
@@ -171,3 +239,15 @@ Request Parameters
    - stack_name: stack_name_url
    - stack_id: stack_id_url
    - snapshot_id: snapshot_id_url
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+
+Response Example
+----------------
+
+The response to this API does not have a body.