Open Stack

On 08/16/2016 02:05 AM, Shuu Mutou wrote:
> Hi Anne,
> 
> AFAIK, the API WG adopted Swagger (OpenAPI) as common tool for API docs.
> Anne, has not the adoption been changed? Otherwise, do we need to maintain much RST files also?
> 
> IMO, for that the reference and the source code doesn't have conflict, these should be near each other as possible as follow. And it decreases maintainance costs for documents, and increases document reliability. So I believe our approach is more ideal.
> 
> The Best: the references generated from source code.
> Better: the references written in docstring.
> 
> We know some projects abandoned these approach, and then they uses RST + YAML. 
> But we hope decreasing maintainance cost for the documents. So we should not create so much RST files, I think.
> 
> 
> I'm proceeding auto-generation of swagger spec from magnum source code using pecan-swagger [1], and improving pecan-swagger with Michael McCune [2].
> These will generate almost Magnum API specs automatically in OpenAPI format.
> Also, these approach can be adopted by other APIs that uses pecan and WSME.
> Please check this also.
> 
> [1] https://review.openstack.org/#/c/303235/
> [2] https://github.com/elmiko/pecan-swagger/
> 
> Regards,
> Shu

There was a pretty public conversation around this transition during the
spring. The highlights include the following facts:

1) No one had done a full stack publish that includes OpenAPI markup in
a project all the way to a Docs site, even though it had been talked
around for 1.5 years.

2) No one had looked at certain features in many of our APIs (actions /
microversions) that don't make to OpenAPI. When we looked in depth, it
was clear that they couldn't be mapped into OpenAPI spec.

3) The moment you use the extensions facility you have to throw away any
community OpenAPI doc generation tools, because you have wandered beyond
spec. No one was signing up for maintaining an OpenAPI toolchain in
OpenStack (related to #1)

4) The only tooling which supports any reasonable site output from
OpenAPI is in javascript. This means that changing how an API is
described is a combination of having to know the python to put this into
the source code, OpenAPI, which is a highly specific formal language,
and javascript. This ends up being the same number of moving parts as
the WADL toolchain, which most people found impenetrable.


So, we did this different RST approach under the theory that it would
lower the barrier to contribution, and thus increase the quality of the
API documentation for our users. And, the results thus far support that
theory. We've merged about 500 patches across projects on this front
since we dove in here.

Is it perfect, definitely not, however this is serving our consumers
much better than any other approach tried so far. Not theoretically, but
actually. Not 'could/can be done' but actually done.

	-Sean

-- 
Sean Dague
http://dague.net