Open Stack

2015-11-06 22:22 GMT+08:00 Anne Gentle <annegentle at justwriteclick.com>:

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

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:
>> 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
>
> __________________________________________________________________________
> 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151106/0d392543/attachment.html>