You might know that the developer.openstack.org site documents over 900GET/PUT/POST/DELETE/PATCH calls for a dozen OpenStack services already on the developer.openstack.org site. As a couple of the keynote speakers in Tokyo so elegantly put it, the trustworthiness and consistency of the OpenStack APIs influenced their decision to run their business workloads in an OpenStack cloud.

Those interfaces need docs, lots of docs, and not only reference docs. While it takes a huge effort to maintain accurate references, we also need to document API usage and scenarios.

Now that we’ve written both an API Guide and a “Writing your first OpenStack application” tutorial, we want the site to be the go-to location for app devs, product developers, and anyone who needs to unlock the power of their OpenStack infrastructure.

In this release, the docs’ platform introduces tooling that lets you migrate from WADL to Swagger and integrate RST-sourced documentation with the API reference documentation. The "why" analysis is clear: we must community-source this info and make it easy to maintain and update so that users can trust it enough to bet their workloads on it.

Why all these changes at this point in the release?

Well, we haven’t had to release the API documentation like we release services documentation. We have done a lot of maintenance on the site, with bug fixing and so on. But it’s time to take the leap. Last release we made a proof-of-concept. This release we unleash a solution that helps us make incremental progress toward our goals.

How do you keep your API docs updated after January 16th?

On January 16th, we’ll migrate the Images API WADL and DocBook files to Swagger and RST files. Then we’ll test the build process and the content itself to validate the migration.

After testing, we will migrate the files for these services:

Identity
Compute
Images
Networks
Block Storage
Object Storage

Then, the remaining services can migrate their files by using the validated tooling.

If you do provide an OpenStack API service, read on.

For the nova project, place your how-to and conceptual articles in the api-guide folder in the nova repository. Other projects can mimic these patches that created an api-guide and build jobs for the Compute api-guide. You continue to update reference information in the openstack/api-site repo. However, the source files have changed.

With this release, you can embed annotations in your source code if you want to generate the reference information. Here’s an example patch from the nova project. Because we haven’t had a project do this yet completely, the build jobs still need to be written.

If your project already has WADL files, they will be migrated to Swagger files and stored in the api-site repository. The WADL files will be deleted; you can retrieve them from Git.

If your project does not have a WADL file, then you write Swagger plus RST to document your API calls, parameters, and reference information. You can generate Swagger from annotations or create Swagger from scratch that you store in the api-site repository. You should review, store, and build RST for conceptual or how-to information from within your project team’s repository.

All projects should use this set of API documentation guidelines from the OpenStack API working group any time their service has a REST API. This document tells you what and how much to write. If you follow the suggested outline, your API guide will be accurate and complete.

After the source files and build jobs exist, the docs are built to developer.openstack.org.

Where can I get help for my project’s API Guides?

These specifications describe the details: Application Developer Guides and Rework API Reference Information.

You can ask questions in #openstack-sdks or #openstack-docs on IRC. We await those magical API docs fairies who grant wishes, but in the meantime but we can point you in the right direction and give you the tools for your quest.