Open Stack

Hi all,

This release I’ve been communicating about moving from WADL to Swagger for
the API reference information on 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160328/31e48f82/attachment.html>