fix api-ref for restore

Keep sync updates with following code.
  [1]. https://review.openstack.org/#/c/370841/
  [2]. https://review.openstack.org/#/c/370819/
  [3]. https://review.openstack.org/#/c/370817/
  [4]. https://review.openstack.org/#/c/375959/

Change-Id: I6271ada24a72a402539599ab212d94da7a377745

api-ref/source/v1/karbor-v1-restores.inc

@@ -103,6 +103,7 @@ Request
    - provider_id: provider_id
    - checkpoint_id: checkpoint_id
    - restore_target: restore_target
+   - restore_auth: restore_auth
    - parameters: restore_parameters
 
 Request Example
@@ -123,6 +124,7 @@ Response
    - provider_id: provider_id
    - checkpoint_id: checkpoint_id
    - restore_target: restore_target
+   - restore_auth: restore_auth
    - parameters: restore_parameters
    - status: restore_status
 

api-ref/source/v1/parameters.yaml

@@ -300,6 +300,13 @@ restore:
   in: body
   required: true
   type: object
+restore_auth:
+  description: |
+    The authentication for restore, include "``type``" "``username``" and
+    "``password``" key.
+  in: body
+  required: true
+  type: dict
 restore_id:
   description: |
     The UUID of the restore.
@@ -314,8 +321,8 @@ restore_list:
   type: array
 restore_parameters:
   description: |
-    The specified parameters for restore, it may include "``username``" and
-    "``password``" for target.
+    specifies each resource or resource type paramters according to protection
+    plugin's restore schema.
   in: body
   required: true
   type: dict

api-ref/source/v1/samples/restore-create-request.json

@@ -3,9 +3,16 @@
     "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
     "checkpoint_id": "dcb20606-ad71-40a3-80e4-ef0fafdad0c3",
     "restore_target": "http://192.168.1.2:35357/v2.0/",
-    "parameters": {
+    "restore_auth": {
+      "type": "password",
       "username": "admin",
       "password": "secretadmin"
+    },
+    "parameters": {
+      "OS::Cinder::Volume": {
+      },
+      "OS::Nova::Server#3f8af6c6-ecea-42bd-b44c-724785bbe5ea": {
+      }
     }
   }
 }

api-ref/source/v1/samples/restore-create-response.json

@@ -5,10 +5,17 @@
     "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
     "checkpoint_id": "dcb20606-ad71-40a3-80e4-ef0fafdad0c3",
     "restore_target": "http://192.168.1.2:35357/v2.0/",
-    "parameters": {
+    "restore_auth": {
+      "type": "password",
       "username": "admin",
       "password": "***"
     },
+    "parameters": {
+      "OS::Cinder::Volume": {
+      },
+      "OS::Nova::Server#3f8af6c6-ecea-42bd-b44c-724785bbe5ea": {
+      }
+    },
     "status": "success"
   }
 }

doc/source/api/api_examples.md

@@ -781,9 +781,16 @@ None
     "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
     "checkpoint_id": "dcb20606-ad71-40a3-80e4-ef0fafdad0c3",
     "restore_target": "http://192.168.1.2:35357/v2.0/",
-    "parameters": {
+    "restore_auth": {
+      "type": "password",
       "username": "admin",
       "password": "secretadmin"
+    },
+    "parameters": {
+      "OS::Cinder::Volume": {
+      },
+      "OS::Nova::Server#3f8af6c6-ecea-42bd-b44c-724785bbe5ea": {
+      }
     }
   }
 }
@@ -798,10 +805,17 @@ None
     "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
     "checkpoint_id": "dcb20606-ad71-40a3-80e4-ef0fafdad0c3",
     "restore_target": "http://192.168.1.2:35357/v2.0/",
-    "parameters": {
+    "restore_auth": {
+      "type": "password",
       "username": "admin",
       "password": "***"
     },
+    "parameters": {
+      "OS::Cinder::Volume": {
+      },
+      "OS::Nova::Server#3f8af6c6-ecea-42bd-b44c-724785bbe5ea": {
+      }
+    },
     "status": "success"
   }
 }