Open Stack

On 05/17/2016 08:57 AM, Jamie Hannaford wrote:
> Hi all,
> 
> 
> Back in March Anne wrote a great summary on the current state of Swagger
> for OpenStack
> docs: http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.
> <http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html>
>  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.
> 
> 
> In terms of the specific limitations that were listed:
> 
> 
> - 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]

If you do this you're now outside the swagger spec, which means that all
the toolchains in swagger that exist to:

* build docs
* build clients
* build tests

No longer apply to your API.

So yes, you could do this, but in doing so you abandon most of the
ecosystem that makes swagger interesting, and now have to maintain all
your own dedicated tooling.

There is no swagger HTML rendering project in OpenStack that can be
simply modified for this. One of the advantages for swagger was that
would be an upstream ecosystem tool to build things like the API site.
You now give that up and take on a multi person year engineering effort
to build a custom documentation site rendering engine (probably in
javascript, as that's where most of the starting components are).
Swagger is also pretty non trivial in the way references are resolved,
so this may end up a *really* big engineering effort.

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

You could go that route, and depending on how often you change your
format, and how big your API is, it may or may not be cumbersome. Fixes
to a base resource would require fixing it in N copies of the file.

It would mean that users of your API must preselect the API version
first before seeing anything. And they will only see a pristine document
at that version.

They will not have access to change notes inline (i.e. "New in 2.12").
When looking at consuming an API. IMHO, that is something which is
incredibly useful in reading an API. It's existence in the python
standard lib makes it much clearer about whether you want to take
advantage of feature X, or decide you'd rather have compatibility, and not.

As with everything, it's trade offs, and what you want to get out of it.

Swagger is a really interesting API Design Language. And if you start
with Swagger when designing your API you impose a set of constraints
that give you a bunch of benefits. If you go beyond it's constraints,
you have imposed a very large and novel DSL on your environment (which
is strictly no longer swagger), which means you get all the costs of
conforming to an external standard without any of the benefits.

I think that our actions interface turned out to be a mistake, but it's
one made so long ago that it's pretty embedded. Long term getting
ourselves out of that hole would be good.

The microversions model is something that I think would be worth
engaging the OpenAPI upstream community. Our current implementation is
pretty OpenStack specific, but the concept would apply to any open
source project with a REST API that is CDed at different rates by
different deployers.

	-Sean

-- 
Sean Dague
http://dague.net