<div dir="ltr">Hi all, <br><br>This release I’ve been communicating about moving from WADL to Swagger for the API reference information on <a href="http://developer.openstack.org">developer.openstack.org</a>. 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.<br><br>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: <a href="https://review.openstack.org/#/c/292420">https://review.openstack.org/#/c/292420</a>.<br><br>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 <a href="http://developer.openstack.org/draft/swagger/">http://developer.openstack.org/draft/swagger/</a> 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.<br><br>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.<br><br>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. <br><br>We'll be writing a new specification as well as presenting at an upstream contributor's talk about Swagger as a standard: <a href="https://www.openstack.org/summit/austin-2016/summit-schedule/events/7723">https://www.openstack.org/summit/austin-2016/summit-schedule/events/7723</a> 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. <br><br>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. <br><br>I'll also attend this week's cross-project meeting to be available for any questions during open discussion.<br><br>Thanks,<br>Anne, who is going to find her copy of the Oh Brother, Where Art Thou soundtrack now<br><br>--<br>Anne Gentle<br>Rackspace<br>Principal Engineer<br><a href="http://www.justwriteclick.com">www.justwriteclick.com</a>
</div>