Open Stack

On 6 November 2015 at 03:31, Alex Xu <soulxu at gmail.com> wrote:
> Hi, folks
>
> Nova API sub-team is working on the swagger generation. And there is PoC
> https://review.openstack.org/233446
>
> But before we are going to next step, I really hope we can get agreement
> with how to support Microversions and Actions. The PoC have demo about
> Microversions. It generates min version action as swagger spec standard, for
> the other version actions, it named as extended attribute, like:
>
> {
>     '/os-keypairs': {
>         "get": {
>             'x-start-version': '2.1',
>             'x-end-version': '2.1',
>             'description': '....',
>            ....
>         },
>         "x-get-2.2-2.9": {
>             'x-start-version': '2.2',
>             'x-end-version': '2.9',
>             'description': '....',
>             .....
>         }
>     }
> }
>
> x-start-version and x-end-version are the metadata for Microversions, which
> should be used by UI code to parse.
>
> This is just based on my initial thought, and there is another thought is
> generating a set full swagger specs for each Microversion. But I think how
> to show Microversions and Actions should be depended how the doc UI to parse
> that also.
>
> As there is doc project to turn swagger to UI:
> https://github.com/russell/fairy-slipper  But it didn't support
> Microversions. So hope doc team can work with us and help us to find out
> format to support Microversions and Actions which good for UI parse and
> swagger generation.
>
> Any thoughts folks?

I can't find the URL to the example, but I though the plan was each
microversion generates a full doc tree.

It also notes the changes between the versions, so you look at the
latest version, you can tell between which versions the API was
modified.

I remember annegentle had a great example of this style, will try ping
here about that next week.

Thanks,
John