api-ref: Verify parameters in os-migrations.inc

Change-Id: I6baeecc4c2d62c3c39d856f5b659cb986a00b724
Implements: blueprint api-ref-in-rst-pike
Closes-Bug: #1668747

api-ref/source/os-migrations.inc

@@ -14,7 +14,7 @@ List Migrations
 
 .. rest_method:: GET /os-migrations
 
-Lists in-progress migrations.
+Lists migrations.
 
 Policy defaults enable only users with the administrative role to perform
 this operation. Cloud providers can change these permissions through the
@@ -22,24 +22,40 @@ this operation. Cloud providers can change these permissions through the
 
 Normal response codes: 200
 
-Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
+Error response codes: unauthorized(401), forbidden(403)
 
 Request
 -------
 
 .. rest_parameters:: parameters.yaml
 
-
-  - status: migration_status
-  - host: migration_host
-  - source_compute: migration_source_compute
-  - migration_type: migration_type
   - hidden: migration_hidden
+  - host: migration_host
   - instance_uuid: migration_instance_uuid
+  - migration_type: migration_type
+  - source_compute: migration_source_compute
+  - status: migration_status
 
 Response
 --------
 
+.. rest_parameters:: parameters.yaml
+
+  - created_at: created
+  - dest_compute: migrate_dest_compute
+  - dest_host: migrate_dest_host
+  - dest_node: migrate_dest_node
+  - id: migration_id
+  - instance_uuid: server_id
+  - new_instance_type_id: migration_new_flavor_id
+  - old_instance_type_id: migration_old_flavor_id
+  - source_compute: migrate_source_compute
+  - source_node: migrate_source_node
+  - status: migrate_status
+  - updated_at: updated
+  - migration_type: migration_type_2_23
+  - links: migration_links_2_23
+
 **Example List Migrations: JSON response**
 
 .. literalinclude:: ../../doc/api_samples/os-migrations/migrations-get.json

api-ref/source/parameters.yaml

@@ -721,9 +721,13 @@ marker:
 migration_hidden:
   description: |
     The 'hidden' setting of migration to filter.
+    The 'hidden' flag is set if the value is 1.
+    The 'hidden' flag is not set if the value is 0.
+    But the 'hidden' setting of migration is always 0,
+    so this parameter is useless to filter migrations.
   in: query
   required: false
-  type: string
+  type: integer
 migration_host:
   description: |
     The source/destination compute node of migration to filter.
@@ -3761,6 +3765,40 @@ migration_id:
   in: body
   required: true
   type: integer
+migration_links_2_23:
+  description: |
+    Links to the migration.
+    This parameter is returned if the migration type is ``live-migration`` and
+    the migration status is one of ``queued``, ``preparing``, ``running``
+    and ``post-migrating``. See `API Guide / Links and References
+    <http://developer.openstack.org/api-guide/compute/links_and_references.html>`_
+    for more info.
+  in: body
+  required: false
+  type: array
+  min_version: 2.23
+migration_new_flavor_id:
+  description: |
+    In ``resize`` case, the flavor ID for resizing the server.
+    In the other cases, this parameter is same as the flavor ID
+    of the server when the migration was started.
+  in: body
+  required: true
+  type: string
+migration_old_flavor_id:
+  description: |
+    The flavor ID of the server when the migration was started.
+  in: body
+  required: true
+  type: string
+migration_type_2_23:
+  description: |
+    The type of the server migration. This is one of ``live-migration``,
+    ``migration``, ``resize`` and ``evacuation``.
+  in: body
+  required: true
+  type: string
+  min_version: 2.23
 migrations:
   description: |
     The list of server migration objects.