From a7dde84ba1dcfa0189271edd8beb0273e6ed9613 Mon Sep 17 00:00:00 2001
From: jichenjc <jichenjc@cn.ibm.com>
Date: Wed, 27 Apr 2016 22:52:42 +0800
Subject: [PATCH] verify api-ref os-migrations.inc

verify the parameters of os-migrations.inc including response and
request. And, add warning for deprecation and incorrect wording of
policy default rule.

looks like the new migration is missing in doc, follow up patch will
add it.

Part of bp:api-ref-in-rst

Change-Id: I8fed7374c34c5c857c8c55f56f86ad4c744844e9
---
 api-ref/source/os-migrations.inc | 23 +++++++++++++-------
 api-ref/source/parameters.yaml   | 36 ++++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 8 deletions(-)

diff --git a/api-ref/source/os-migrations.inc b/api-ref/source/os-migrations.inc
index 9066a6f6e3..94b2414d9b 100644
--- a/api-ref/source/os-migrations.inc
+++ b/api-ref/source/os-migrations.inc
@@ -1,14 +1,14 @@
 .. -*- rst -*-
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
-============================
- Migrations (os-migrations)
-============================
+=========================================
+ Migrations (os-migrations) (frozen)
+=========================================
 
 Shows data on migrations.
 
+.. warning:: The old top-level resource `/os-migrations` is frozen,
+             it won't be extended anymore. Use /servers/{uuid}/migrations instead.
+
 List Migrations
 ===============
 
@@ -16,8 +16,9 @@ List Migrations
 
 Lists in-progress migrations.
 
-Policy defaults enable only users with the administrative role or the owner of the server to perform this 
-operation. Cloud providers can change these permissions through the ``policy.json`` file.
+Policy defaults enable only users with the administrative role to perform
+this operation. Cloud providers can change these permissions through the
+``policy.json`` file.
 
 Normal response codes: 200
 
@@ -29,6 +30,12 @@ Request
 .. rest_parameters:: parameters.yaml
 
   - tenant_id: tenant_id
+  - status: migration_status
+  - host: migration_host
+  - source_compute: migration_source_compute
+  - migration_type: migration_type
+  - hidden: migration_hidden
+  - instance_uuid: migration_instance_uuid
 
 Response
 --------
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 9019482578..4eaed8ecc0 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -422,6 +422,42 @@ marker:
   in: query
   required: false
   type: string
+migration_hidden:
+  description: |
+    The 'hidden' setting of migration to filter.
+  in: query
+  required: false
+  type: string
+migration_host:
+  description: |
+    The source/destination compute node of migration to filter.
+  in: query
+  required: false
+  type: string
+migration_instance_uuid:
+  description: |
+    The uuid of the instance that migration is operated on to filter.
+  in: query
+  required: false
+  type: string
+migration_source_compute:
+  description: |
+    The source compute node of migration to filter.
+  in: query
+  required: false
+  type: string
+migration_status:
+  description: |
+    The status of migration to filter.
+  in: query
+  required: false
+  type: string
+migration_type:
+  description: |
+    The type of migration to filter.
+  in: query
+  required: false
+  type: string
 minDisk:
   description: |
     Filters the response by a minimum disk space, in GiB.