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