From 57330a12a851a72b781fb48ad23bfda894d051b8 Mon Sep 17 00:00:00 2001
From: lihaijing <lihaijing@fiberhome.com>
Date: Mon, 26 Jun 2017 15:18:09 +0800
Subject: [PATCH] Api-ref: add documentation for v2/v3 backup 'os-reset_status'
 action

There is no document about v2/v3 backup 'os-reset_status' action. This
action explicitly updates the backup state. So add the missing content.

Change-Id: Ie0dd2b4e184d09e957c4ba296544f5019d05fda3
Partial-Bug: #1607539
---
 api-ref/source/v2/ext-backups-actions-v2.inc  | 37 +++++++++++++++++--
 api-ref/source/v2/parameters.yaml             |  8 +++-
 .../samples/backup-reset-status-request.json  |  5 +++
 api-ref/source/v3/ext-backups-actions-v3.inc  | 36 ++++++++++++++++--
 api-ref/source/v3/parameters.yaml             |  8 +++-
 .../samples/backup-reset-status-request.json  |  5 +++
 6 files changed, 90 insertions(+), 9 deletions(-)
 create mode 100644 api-ref/source/v2/samples/backup-reset-status-request.json
 create mode 100644 api-ref/source/v3/samples/backup-reset-status-request.json

diff --git a/api-ref/source/v2/ext-backups-actions-v2.inc b/api-ref/source/v2/ext-backups-actions-v2.inc
index 5a2f4c4791b..85ebf15f35a 100644
--- a/api-ref/source/v2/ext-backups-actions-v2.inc
+++ b/api-ref/source/v2/ext-backups-actions-v2.inc
@@ -3,7 +3,7 @@
 Backup actions (backups, action)
 ================================
 
-Force-deletes a backup.
+Force-deletes a backup and reset status for a backup.
 
 
 Force-delete backup
@@ -18,9 +18,8 @@ This operations deletes the backup and any backup data.
 The backup driver returns the ``405`` status code if it does not
 support this operation.
 
-Normal response codes: 202,
-
-Error response codes:404,405,
+Normal response codes: 202
+Error response codes: itemNotFound(404), badMethod(405)
 
 
 Request
@@ -37,3 +36,33 @@ Request Example
 
 .. literalinclude:: ./samples/backup-force-delete-request.json
    :language: javascript
+
+
+
+Reset backup's status
+~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v2/{tenant_id}/backups/{backup_id}/action
+
+Reset a backup's status. Specify the ``os-reset_status`` action in the request body.
+
+Normal response codes: 202
+Error response codes: badRequest(400), itemNotFound(404)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status_7
+   - os-reset_status: os-reset_status
+   - tenant_id: tenant_id
+   - backup_id: backup_id
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/backup-reset-status-request.json
+   :language: javascript
+
diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml
index a91c42c5ef8..afbfd10034b 100644
--- a/api-ref/source/v2/parameters.yaml
+++ b/api-ref/source/v2/parameters.yaml
@@ -17,7 +17,7 @@ backup_id:
   description: |
     The UUID for a backup.
   in: path
-  required: false
+  required: true
   type: string
 cascade:
   description: |
@@ -1571,6 +1571,12 @@ status_6:
   in: body
   required: false
   type: string
+status_7:
+  description: |
+    The status for the backup.
+  in: body
+  required: true
+  type: string
 storage_protocol:
   description: |
     The storage back end for the back-end volume. For
diff --git a/api-ref/source/v2/samples/backup-reset-status-request.json b/api-ref/source/v2/samples/backup-reset-status-request.json
new file mode 100644
index 00000000000..b18b65a68e7
--- /dev/null
+++ b/api-ref/source/v2/samples/backup-reset-status-request.json
@@ -0,0 +1,5 @@
+{
+    "os-reset_status": {
+        "status": "available"
+    }
+}
diff --git a/api-ref/source/v3/ext-backups-actions-v3.inc b/api-ref/source/v3/ext-backups-actions-v3.inc
index cbd0e50cbdc..0c3f35d4c08 100644
--- a/api-ref/source/v3/ext-backups-actions-v3.inc
+++ b/api-ref/source/v3/ext-backups-actions-v3.inc
@@ -3,7 +3,7 @@
 Backup actions (backups, action)
 ================================
 
-Force-deletes a backup.
+Force-deletes a backup and reset status for a backup.
 
 
 Force-delete a backup
@@ -18,8 +18,8 @@ This operations deletes the backup and any backup data.
 The backup driver returns the ``405`` status code if it does not
 support this operation.
 
-Error response codes:404,405,202,
-
+Normal response codes: 202
+Error response codes: itemNotFound(404), badMethod(405)
 
 Request
 -------
@@ -35,3 +35,33 @@ Request Example
 
 .. literalinclude:: ./samples/backup-force-delete-request.json
    :language: javascript
+
+
+
+Reset a backup's status
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/backups/{backup_id}/action
+
+Reset a backup's status. Specify the ``os-reset_status`` action in the request body.
+
+Normal response codes: 202
+Error response codes: badRequest(400), itemNotFound(404)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status_10
+   - os-reset_status: os-reset_status
+   - project_id: project_id_path
+   - backup_id: backup_id
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/backup-reset-status-request.json
+   :language: javascript
+
diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index f328de97324..fe9de28dad8 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@@ -29,7 +29,7 @@ backup_id:
   description: |
     The UUID for a backup.
   in: path
-  required: false
+  required: true
   type: string
 cascade:
   description: |
@@ -1875,6 +1875,12 @@ status_1:
   in: body
   required: true
   type: string
+status_10:
+  description: |
+    The status for the backup.
+  in: body
+  required: true
+  type: string
 status_2:
   description: |
     The status for the snapshot.
diff --git a/api-ref/source/v3/samples/backup-reset-status-request.json b/api-ref/source/v3/samples/backup-reset-status-request.json
new file mode 100644
index 00000000000..b18b65a68e7
--- /dev/null
+++ b/api-ref/source/v3/samples/backup-reset-status-request.json
@@ -0,0 +1,5 @@
+{
+    "os-reset_status": {
+        "status": "available"
+    }
+}