[openstack-dev] [nova] [doc] How to support Microversions and Actions in Swagger Spec

Anne Gentle annegentle at justwriteclick.com
Fri Nov 6 14:22:08 UTC 2015


On Thu, Nov 5, 2015 at 9:31 PM, 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.
>

The swagger.io editor will not necessarily recognize extended attributes
(x- are extended attributes), right? I don't think we intend for these
files to be hand-edited once they are generated, though, so I consider it a
non-issue that the editor can't edit microversioned source.


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

Last release was a proof of concept for being able to generate Swagger.
Next we'll bring fairy-slipper into OpenStack and work with the API working
group and the Nova API team to enhance it.

This release we can further enhance with microversions. Nothing's
preventing that to my knowledge, other than Russell needs more input to
make the output what we want. This email is a good start.

I'm pretty sure microversions are hard to document no matter what we do so
we just need to pick a way and move forward. Here's what is in the spec:
For microversions, we'll need at least 2 copies of the previous reference
info (enable a dropdown for the user to choose a prior version or one that
matches theirs) Need to keep deprecated options.  An example of version
comparisons https://libgit2.github.com/libgit2/#HEAD

Let's discuss weekly at both the Nova API meeting and the API Working group
meeting to refine the design. I'm back next week and plan to update the
spec.
Anne



>
> Any thoughts folks?
>
> Thanks
> Alex
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151106/aa481585/attachment.html>


More information about the OpenStack-dev mailing list