<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Nov 5, 2015 at 9:31 PM, Alex Xu <span dir="ltr"><<a href="mailto:soulxu@gmail.com" target="_blank">soulxu@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div>Hi, folks</div><div><br></div>Nova API sub-team is working on the swagger generation. And there is PoC <a href="https://review.openstack.org/233446" target="_blank">https://review.openstack.org/233446</a><div><br></div><div>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:</div><div><br></div><div>{</div><div> '/os-keypairs': {</div><div> "get": {<br></div><div> 'x-start-version': '2.1',</div><div> 'x-end-version': '2.1',</div><div> 'description': '....',</div><div> ....</div><div> },</div><div> "x-get-2.2-2.9": {</div><div> 'x-start-version': '2.2',</div><div> 'x-end-version': '2.9',</div><div> 'description': '....',</div><div> .....</div><div> }</div><div> }</div><div>}</div><div><br></div><div>x-start-version and x-end-version are the metadata for Microversions, which should be used by UI code to parse.<br></div></div></blockquote><div><br></div><div>The <a href="http://swagger.io">swagger.io</a> 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.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div></div><div><br></div><div>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. </div><div><br></div><div>As there is doc project to turn swagger to UI: <a href="https://github.com/russell/fairy-slipper" target="_blank">https://github.com/russell/fairy-slipper</a> 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.</div></div></blockquote><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>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:<br>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 <a href="https://libgit2.github.com/libgit2/#HEAD">https://libgit2.github.com/libgit2/#HEAD</a></div><div><br></div><div>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. </div><div>Anne</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><br></div><div>Any thoughts folks?</div><div><br></div><div>Thanks</div><span><font color="#888888"><div>Alex</div><div><br></div></font></span></div>
<br>__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br><br clear="all"><div><br></div>-- <br><div><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>