GET /os-migrations sample has incorrect sort order

[Matt Riedemann]

The API reference sample for the GET /os-migrations API with the 2.59 microversion:

https://developer.openstack.org/api-ref/compute/?expanded=list-migrations-detail#list-migrations

Shows an incorrect sort order. The returned migrations are sorted by [created_at, id] in descending order:

https://github.com/openstack/nova/blob/c64b03d218c4d05b9db47eaf7660cdab9baa6468/nova/api/openstack/compute/migrations.py#L158

The response sample shows several random migration records and they aren't sorted by created_at in descending order, because the sample is based on stubs in the functional test:

https://github.com/openstack/nova/blob/c64b03d218c4d05b9db47eaf7660cdab9baa6468/nova/tests/functional/api_sample_tests/test_migrations.py#L193

Since the API reference does not mention what the sort order is, a user might have to guess from the sample, which would be pretty much impossible with the existing sample.

With this bug, the API reference sample should:

1. Fix the sample response data to use proper sort order from the API for the 2.59 samples (since there is no guaranteed sort order for microversion < 2.59, especially with multiple cells).

2. Mention the sort order in the API reference when using microversion 2.59+.

[Takashi Natsume (natsume-takashi)]

The v2.59 example has already sorted by created_at in descending order.
So add a description about the sort order in the API reference when using microversion 2.59+.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/616773

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/616773
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=084ce9b28af1320d17ff3ebf63d23f7830019982
Submitter: Zuul
Branch: master

commit 084ce9b28af1320d17ff3ebf63d23f7830019982
Author: Takashi NATSUME <email address hidden>
Date: Fri Nov 9 14:17:07 2018 +0900

    api-ref: Add a description about sort order

    Add a description about the sort order
    in the "List Migrations" (GET /os-migrations) API.

    Change-Id: Iaa8e264ca95b69f3c97a6848918862ee22922de1
    Closes-Bug: #1801789

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/nova 19.0.0.0rc1 release candidate.