<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, May 17, 2016 at 9:13 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:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">All great points, thanks Anne and Sean. My responses are inline.<br>
From: Sean Dague <<a href="mailto:sean@dague.net">sean@dague.net</a>><br>
Sent: 17 May 2016 15:30<br>
To: <a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a><br>
Subject: Re: [openstack-dev] [docs] [api] Swagger limitations?<br>
<div><div class="h5"><br>
On 05/17/2016 08:57 AM, Jamie Hannaford wrote:<br>
> Hi all,<br>
> Back in March Anne wrote a great summary on the current state of Swagger<br>
> for OpenStack<br>
> docs: <a href="http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html" rel="noreferrer" target="_blank">http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html</a>.<br>
> <<a href="http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html" rel="noreferrer" target="_blank">http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html</a>><br>
>  Is this still the current state of things? Magnum is looking to<br>
> document its API soon, so I want to look at the feasibility of doing it<br>
> in Swagger. If it's not possible, RST should suffice.<br>
> In terms of the specific limitations that were listed:<br>
> - the /actions endpoint. Would it be possible to use vendor extensions<br>
> to solve this problem? For example, imagine that you want to document<br>
> reboot and rebuild operations. You could create custom verb properties<br>
> for these operations (`x-post-reboot`, `x-post-rebuild`) that would<br>
> allow differentiation of the JSON payload under the same URL category.<br>
> The HTML rendering would need to be adapted to take this into<br>
> consideration. [1]<br>
If you do this you're now outside the swagger spec, which means that all<br>
the toolchains in swagger that exist to:<br>
* build docs<br>
* build clients<br>
* build tests<br>
No longer apply to your API.<br>
So yes, you could do this, but in doing so you abandon most of the<br>
ecosystem that makes swagger interesting, and now have to maintain all<br>
your own dedicated tooling.<br>
There is no swagger HTML rendering project in OpenStack that can be<br>
simply modified for this. One of the advantages for swagger was that<br>
would be an upstream ecosystem tool to build things like the API site.<br>
You now give that up and take on a multi person year engineering effort<br>
to build a custom documentation site rendering engine (probably in<br>
javascript, as that's where most of the starting components are).<br>
Swagger is also pretty non trivial in the way references are resolved,<br>
so this may end up a *really* big engineering effort.<br>
</div></div>I agree, but I don't think it's an unreasonable compromise to make because, at least in the context of OpenStack's ecosystem, we already provide much of that tooling to end-users. We have a plethora of clients already out there and a project underway to unify them into a single client. So I don't think we'd be putting users at a disadvantage by using our own vendor extensions, so long as they're well designed and well documented.<br>
The only inconvenience would be to adapt the build process to take custom verbs into consideration. In my opinion that's more of a short-term software challenge for contributors rather than an insurmountable one that affects end-users. Then again, I don't have much experience with the build/infra process, so please call me out if that's a complete mischaracterisation :)<br>
While I accept that it's definitely preferable to use upstream tools when they're useful, with such a complex beast like OpenStack, how long do you think we could carry on using vanilla upstream tools? At some point we would probably need to roll out our own modifications to satisfy our use cases. In terms of it requiring a multi-person engineering effort, isn't that already the remit of the current docs team?<br></blockquote><div><br></div><div>In a word, No. We have not had dedicated development resources specifically for API docs since 2013.</div><div><br></div><div>Do you have ideas for how to bring this type of development resource into the OpenStack community? I've tried. I have worked on this for fairy-slipper, with the API working group, and with the docs tools team, and it leaves me with the sense that we must prioritize due to lack of development resources.</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class=""><br>
> - microversions. The more I think about it, the more I realise that this<br>
> is not really a Swagger limitation but more of a consideration that<br>
> *any* documentation format needs to solve. It seems that per<br>
> microversion release, a separate doc artefact is required which<br>
> encapsulates the API at that point in time. This would be very easy to<br>
> do in Swagger compared to RST (single file vs directory of RST files).<br>
You could go that route, and depending on how often you change your<br>
format, and how big your API is, it may or may not be cumbersome. Fixes<br>
to a base resource would require fixing it in N copies of the file.<br>
</span>If my understanding is correct, this would not happen. Each microversion, when released, is locked and would be preserved in that doc artefact. If a new software release is needed to fix a bug, that change would be encapsulated in a microversion with its own doc file.<br>
<span class=""><br>
It would mean that users of your API must preselect the API version<br>
first before seeing anything. And they will only see a pristine document<br>
at that version.<br>
They will not have access to change notes inline (i.e. "New in 2.12").<br>
When looking at consuming an API. IMHO, that is something which is<br>
incredibly useful in reading an API. It's existence in the python<br>
standard lib makes it much clearer about whether you want to take<br>
advantage of feature X, or decide you'd rather have compatibility, and not.<br>
</span>I definitely agree that this information is useful for the user, but I think it belongs in a RELEASENOTES format, not API docs. I think we should get to a position where API versioning is treated with the importance it deserves. The user should understand what version they want to interact with and make a decision, and then be presented with that API documentation.<br>
In terms of the logic of how we can re-use doc artefacts, we could do something like the following:<br>
* if a microversion which is selected by a user has a specific doc artefact, show it<br>
* if a specific microversion document does not exist, find its nearest sibling. For example, if no document was published for microversions 1.100 or 1.99, but there was one published for 1.98, it is reasonable to assume that both 1.100 and 1.99 have the same API as 1.98, and can therefore use its doc artefact<br>
<span class=""><br>
As with everything, it's trade offs, and what you want to get out of it.<br>
Swagger is a really interesting API Design Language. And if you start<br>
with Swagger when designing your API you impose a set of constraints<br>
that give you a bunch of benefits. If you go beyond it's constraints,<br>
you have imposed a very large and novel DSL on your environment (which<br>
is strictly no longer swagger), which means you get all the costs of<br>
conforming to an external standard without any of the benefits.<br>
I think that our actions interface turned out to be a mistake, but it's<br>
one made so long ago that it's pretty embedded. Long term getting<br>
ourselves out of that hole would be good.<br>
</span>Completely agree. The good news is that the API-WG have a spec in review (<a href="https://review.openstack.org/#/c/234994/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/234994/</a>) which might solve these problems. They want to make actions first-class resources in the API. From my initial understanding, this could be represented in Swagger without the need for vendor extensions.<br></blockquote><div><br></div><div>Sure, but the API WG is for new API designs. </div><div><br></div><div>This is the crux of the issue. For Magnum, you're probably fine with Swagger/OpenAPI and we are not preventing you from working on it. For existing APIs we have what we have and need to brutally prioritize in order to meet user's needs for services that are already deployed and in use for thousands of users. </div><div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class="im HOEnZb"><br>
The microversions model is something that I think would be worth<br>
engaging the OpenAPI upstream community. Our current implementation is<br>
pretty OpenStack specific, but the concept would apply to any open<br>
source project with a REST API that is CDed at different rates by<br>
different deployers.<br>
Sean Dague<br>
<a href="http://dague.net" rel="noreferrer" target="_blank">http://dague.net</a><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>
</span><span class="im HOEnZb">________________________________<br>
Rackspace International GmbH a company registered in the Canton of Zurich, Switzerland (company identification number CH- 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" rel="noreferrer" 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">abuse@rackspace.com</a> and delete the original message. Your cooperation is appreciated.<br>
</span><div class="HOEnZb"><div class="h5">__________________________________________________________________________<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>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>Anne Gentle</div><div><a href="http://www.justwriteclick.com" style="font-size:12.8px" target="_blank">www.justwriteclick.com</a><br></div></div></div></div></div>