2015-11-06 22:22 GMT+08:00 Anne Gentle <[email protected]>:
> > > On Thu, Nov 5, 2015 at 9:31 PM, Alex Xu <[email protected]> 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. > > yes, right. The editor can just ignore the extended attributes. I just want to show if we have something more than swagger standard spec to support Microversions and Actions, we should use swagger spec supported way to extend. > >> 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. > yea, really appreciate if Russell can give some input as he work on fairy-slipper. > > 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. > yea, let's talk more at next meeting, thanks! > Anne > > > >> >> Any thoughts folks? >> >> Thanks >> Alex >> >> >> __________________________________________________________________________ >> OpenStack Development Mailing List (not for usage questions) >> Unsubscribe: >> [email protected]?subject:unsubscribe >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> >> > > > -- > Anne Gentle > Rackspace > Principal Engineer > www.justwriteclick.com > > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: [email protected]?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > >
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
