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

@@ -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
 --------

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.