[openstack-dev] [docs] [api] Oh Swagger, where art thou?

Sean Dague sean at dague.net
Tue Mar 29 11:56:54 UTC 2016

Some additional links to what this sort of looks like right now -

Which is built off an RST file that looks like - http://tinyurl.com/hjqpjdm

The notable additions are the ".. rest_method::" stanza, which is what
provides the collapsing method sections (as are in the current api-ref

As well as the ".. rest_parameters::" stanza which takes a list of
parameter names, and lookup keys to an external yaml file. This allows
for building the tables for these parameters much in the same way as the
existing WADL does but in a way where long for description can be easily
done. (Tables + rst are a bit cumbersome in the base case).

The #1 Goal here is better docs for Humans. In all cases today, Humans
are the primary consumers of our API, building software that uses. A
large number of the current API docs have inaccuracies or are generally
confusing because few people have been able to ventured into the WADL to
make more than small typographic changes.

Getting over to an RST base, that is content first in approach, will
hopefully open up the effort to more contributors.

Swagger is neat. But it's important to remember it's actually an API
Design Tool, which provides the benefit of some documentation tooling
around it. If used in the Design phase of an API it imposes a set of
constraints that help build a solid API. Retrofiting to swagger is at
best difficult, and some of the features our APIs use make it impossible.

This POC has mostly been about demonstrating what a content first
approach could be, where we could plug in structured / semi-structured
data via sphinx extensions. In phase 1, that will be our custom quick
and dirty markup format that's swagger inspired. In the future projects
could replace some of these plug points with other structured content in
their projects, like jsonschema / swagger / raml, whatever is appropriate.

However, we need to make sure we don't delay moving forward to get off a
WADL base until we've perfected any of those other approaches. We're
living on brownfield that is on fire. Getting to higher ground is
priority one. Iterating after we're there will continue to happen.

There is a cross project design summit session proposed for this work as
well, so we can show current status and discuss futures on this.

As always, comments and questions welcomed. Our giant etherpad of doom
in poking at this work, and what's been discovered is here -


On 03/28/2016 06:21 PM, Anne Gentle wrote:
> Hi all,
> This release I’ve been communicating about moving from WADL to Swagger
> for the API reference information on developer.openstack.org
> <http://developer.openstack.org>. What we've discovered on the journey
> is that Swagger doesn't match well for our current API designs (details
> below), and while we're not completely giving up on Swagger, we're also
> recognizing the engineering effort to maintain and sustain those efforts
> isn't going to magically appear.
> Sean Dague has put together a proof-of-concept with Compute servers
> reference documentation to use Sphinx, RST, parameters files, and some
> Sphinx extensions to do a near-copy representation of the API reference
> page. We've met with the Nova API team, the API working group, and other
> interested developers to make sure our ideas are sound, and so far we
> have consensus on forging a new path forward. The review patch is here:
> https://review.openstack.org/#/c/292420.
> I believe we can still find uses for the Swagger migration for some
> projects that match the specification really well. We'll keep outputting
> the draft Swagger files to http://developer.openstack.org/draft/swagger/
> and continue to look for the use case for Swagger. Perhaps it's a
> try-it-out connection to TryStack. Maybe some projects will want to
> build clients from those files. We know it's useful, but need to focus
> efforts for now.
> We know that some OpenStack APIs cannot fit Swagger’s model. For
> example, Compute, File Storage, Bare Metal, and Block Storage (nova,
> manila, ironic, and cinder projects) have microversions enabled for
> updates to the request body as we continue to evolve the API definition,
> and Swagger has no mechanism to display the changes between
> microversions for end-users. As another example, Compute, Block Storage,
> File Storage, Databases, and Networks APIs (nova, cinder, manila, trove,
> and neutron projects) have an /actions resource that allows multiple
> differing request bodies.
> I'm writing this email to let you all know there's a new plan coming. We
> are using pieces of work from the past efforts to get the best outcome
> for sustainable, useful API documentation. The API Reference and WADL
> files will remain in the api-site repo until we have a new publishing
> job that we can use to flip the switch.
> We'll be writing a new specification as well as presenting at an
> upstream contributor's talk about Swagger as a standard:
> https://www.openstack.org/summit/austin-2016/summit-schedule/events/7723
> Once we get the publishing pipeline established, look for review
> proposals to your project repos to store API docs there rather than in
> api-site.
> We're going to reboot the migration and get off of WADL. Three cheers
> for that. If you’d like to work on these efforts, please stay tuned to
> the usual mailing list channels and if you are a docs or API working
> group liaison, please stay up-to-date with the plans. Review the
> upcoming specification, look for API docs patches in your repo, review
> those, and keep the efforts moving.
> I'll also attend this week's cross-project meeting to be available for
> any questions during open discussion.
> Thanks,
> Anne, who is going to find her copy of the Oh Brother, Where Art Thou
> soundtrack now
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com <http://www.justwriteclick.com>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Sean Dague

More information about the OpenStack-dev mailing list