<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<style type="text/css" style="display:none"><!-- p { margin-top: 0px; margin-bottom: 0px; }--></style>
</head>
<body dir="ltr" style="font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;">
<p>Hi Anne,<br>
</p>
<p><br>
</p>
<p>So it seems that the only remaining issues are:</p>
<p><br>
</p>
<p>- using $ref, which is not supported by some upstream tools<br>
</p>
<p>- embedding Heat templates in a Swagger doc (not applicable to most OpenStack services)<br>
</p>
<p><br>
</p>
<p>I responded to the other two in my e-mail to Sean. For the $ref problem, what is the problem with using NPM packages like swagger-tools or swagger-parser [1][2]? They can deference Swagger files into one unified file, which the build tool can then use for
HTML rendering. The alternative is to let<span style="font-size: 12pt;"> each project choose whether to use $ref or not. If they do</span><span style="font-size: 12pt;"> want to spread Swagger docs out into separate documents and reference them, they will
need to use a tool in whatever language that works.</span></p>
<p><br>
</p>
<p>I agree that Swagger is a new tool in a new ecosystem, but it definitely solves a lot of our use cases. I think it'd be a lot stronger if we adopted it - at least partially - and contributed our ideas for improvement back upstream.<br>
</p>
<p><br>
</p>
<p>Was there any cons/disadvantages that I missed which would prevent is incorporating it?<br>
</p>
<p><br>
</p>
<p>Jamie<br>
</p>
<p><br>
</p>
<p>[1] <a href="https://www.npmjs.com/package/swagger-parser">https://www.npmjs.com/package/swagger-parser</a> <br>
</p>
<p>[2] <a href="https://github.com/jamiehannaford/swagger-magnum/blob/master/deref.js">https://github.com/jamiehannaford/swagger-magnum/blob/master/deref.js</a> <br>
</p>
<p><br>
</p>
<div style="color: rgb(33, 33, 33);">
<hr tabindex="-1" style="display:inline-block; width:98%">
<div id="divRplyFwdMsg" dir="ltr"><font face="Calibri, sans-serif" color="#000000" style="font-size:11pt"><b>From:</b> Anne Gentle <annegentle@justwriteclick.com><br>
<b>Sent:</b> 17 May 2016 15:35<br>
<b>To:</b> OpenStack Development Mailing List (not for usage questions)<br>
<b>Subject:</b> Re: [openstack-dev] [docs] [api] Swagger limitations?</font>
<div> </div>
</div>
<div>
<div dir="ltr"><br>
<div class="gmail_extra"><br>
<div class="gmail_quote">On Tue, May 17, 2016 at 7:57 AM, Jamie Hannaford <span dir="ltr">
<<a href="mailto:jamie.hannaford@rackspace.com" target="_blank">jamie.hannaford@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex; border-left-width:1px; border-left-style:solid; border-left-color:rgb(204,204,204); padding-left:1ex">
<div dir="ltr" style="font-size:12pt; color:rgb(0,0,0); font-family:Calibri,Arial,Helvetica,sans-serif; background-color:rgb(255,255,255)">
<p>Hi all,<br>
</p>
<p><br>
</p>
<p>Back in March Anne wrote a great summary on the current state of Swagger for OpenStack docs: <a href="http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html" target="_blank">http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.</a>
<span style="font-size:12pt">Is this still the current state of things? Magnum is looking to document its API soon, so I want to look at the feasibility of doing it in Swagger. If it's not possible, RST should suffice.</span></p>
<p><br>
</p>
</div>
</blockquote>
<div><br>
</div>
<div dir="ltr" style="text-align: left;">Hi Jamie, thanks for asking. There are a few more limitations/concerns that I'll outline below.</div>
<div dir="ltr" style="text-align: left;"></div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex; border-left-width:1px; border-left-style:solid; border-left-color:rgb(204,204,204); padding-left:1ex">
<div dir="ltr" style="font-size:12pt; color:rgb(0,0,0); font-family:Calibri,Arial,Helvetica,sans-serif; background-color:rgb(255,255,255)">
<p></p>
<p>In terms of the specific limitations that were listed:<br>
</p>
<p><br>
</p>
<p>- the /actions endpoint. Would it be possible to use vendor extensions to solve this problem? For example, imagine that you want to document reboot and rebuild operations. You could create custom verb properties for these operations (`x-post-reboot`, `x-post-rebuild`)
that would allow differentiation of the JSON payload under the same URL category. The HTML rendering would need to be adapted to take this into consideration. [1]<br>
</p>
<p><br>
</p>
</div>
</blockquote>
<div>Yes, our first goal is to migrate off of WADL, but that won't prevent use of Swagger, it just means the first priority is to get all projects off of WADL. </div>
<div><br>
</div>
<div>I think the details and nuances here were fairly well communicated in the rest of the thread [1] and in the etherpads, but of course that requires a LOT of reading. :)</div>
<div><br>
</div>
<div>The main points I'd also like to ensure you know we discussed are [2]:</div>
----<br>
The current Plan of Record is to move to swagger. However this doesn't address a number of key issues:<br>
- swagger is young, most community tools around swagger are 50% - 80% solutions<br>
- swagger provides no facility for nova's 'action' interfaces or microversions <br>
<br>
NOTE: actions are used by nova, cinder, manilla, trove, neutron (in extensions) - so 40% of the 12 APIs documented on
<a href="http://developer.openstack.org/" target="_blank">http://developer.openstack.org/</a> but only 5 of 19 (26%) REST APIs in OpenStack's governance<br>
<br>
NOTE: microversions are used by nova, manilla, ironic, and cinder (and neutron probably in the future unless it proves awful to document and use)<br>
<br>
NOTE: while Heat neither uses actions or microversions, it's content templates as inline post requests makes the swagger definition potentially really tough. Not that there shouldn't be full docs for those formats, but they just don't do that today. This same
issue will hit other APIs that support post requests of 3rd party content format. Tacker being a good instance.<br>
<br>
- the swagger-tools npm package supports $ref, which will clearly be required for maintaining our APIs (autoconverted Nova API is 21KLOC, and probably would be triple that once missing parts are filled in).<br>
<br>
NOTE: this is a brand new toolchain that is yet another speed bump in getting people to contribute and maintain, though it is maintained outside of OpenStack
<div>---</div>
<div><br>
</div>
<div>Please do consider the additional concerns about $ref and tooling listed above.</div>
<div><br>
</div>
<div>In all the communication, I have not prevented the use of Swagger/OpenAPI but I want to make it clear that focused efforts are best for the earliest projects. </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex; border-left-width:1px; border-left-style:solid; border-left-color:rgb(204,204,204); padding-left:1ex">
<div dir="ltr" style="font-size:12pt; color:rgb(0,0,0); font-family:Calibri,Arial,Helvetica,sans-serif; background-color:rgb(255,255,255)">
<p></p>
<p>- microversions. The more I think about it, the more I realise that this is not really a Swagger limitation but more of a consideration that *any* documentation format needs to solve. It seems that per microversion release, a separate doc artefact is required
which encapsulates the API at that point in time. This would be very easy to do in Swagger compared to RST (single file vs directory of RST files). </p>
<p><br>
</p>
</div>
</blockquote>
<div>Agreed. But are we going to solve the microversions display problem once or twice? Right now, I'm focusing on RST + YAML, and microversions need to be solved.</div>
<div><br>
</div>
<div>Plus I'd like your thoughts on maintenance of the $ref mechanism and HTML publishing toolchain. We have a patch that lets us build to HTML using npm-provided tooling [3], but I really need to focus on getting a navigation for all OpenStack APIs to be read
in a unified way on <a href="http://developer.openstack.org">developer.openstack.org</a> so I haven't tried to make a nice header/footer on that output.
</div>
<div><br>
</div>
<div>Heh, I see Sean replying also, so I'll go ahead and send. Thanks Jamie.</div>
<div><br>
</div>
<div>Anne<br>
</div>
<div> </div>
<div>1. <a href="http://lists.openstack.org/pipermail/openstack-dev/2016-March/090704.html" target="_blank">
http://lists.openstack.org/pipermail/openstack-dev/2016-March/090704.html</a></div>
<div>2. <a href="https://etherpad.openstack.org/p/api-site-in-rst" target="_blank">https://etherpad.openstack.org/p/api-site-in-rst</a></div>
<div>3. <a href="https://review.openstack.org/#/c/286659/">https://review.openstack.org/#/c/286659/</a> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex; border-left-width:1px; border-left-style:solid; border-left-color:rgb(204,204,204); padding-left:1ex">
<div dir="ltr" style="font-size:12pt; color:rgb(0,0,0); font-family:Calibri,Arial,Helvetica,sans-serif; background-color:rgb(255,255,255)">
<p></p>
<p>Am I way off here? I would really like to hear others' opinions on this. Thanks for all the great work!<br>
</p>
<p><br>
</p>
<p>Jamie<br>
</p>
<p><br>
</p>
<p>[1] <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/EXTENSIONS.md" target="_blank">https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/EXTENSIONS.md</a> <br>
</p>
<hr>
Rackspace International GmbH a company registered in the Canton of Zurich, Switzerland (company identification number CH-020.4.047.077-1) whose registered office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland. Rackspace International GmbH privacy policy
can be viewed at <a href="http://www.rackspace.co.uk/legal/swiss-privacy-policy" target="_blank">
www.rackspace.co.uk/legal/swiss-privacy-policy</a> - This e-mail message may contain confidential or privileged information intended for the recipient. Any dissemination, distribution or copying of the enclosed material is prohibited. If you receive this transmission
in error, please notify us immediately by e-mail at <a href="mailto:abuse@rackspace.com" target="_blank">
abuse@rackspace.com</a> and delete the original message. Your cooperation is appreciated.
</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>
<div dir="ltr">
<div>Anne Gentle</div>
<div><a href="http://www.justwriteclick.com" target="_blank" style="font-size:12.8px">www.justwriteclick.com</a><br>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<br>
</body>
</html>