Open Stack

I work on the Cue project at HP and I’m working on auto-generating our API documentation. I’m also keeping up with the changes and ongoing migrations at openstack docs. The new RST work documentation looks awesome for the user guides, but I’m very interested in where the api-docs are headed and how I can help get the ball rolling in a strong direction. 

I’m working with elmiko’s pecan-swagger plugin [1] and have a version that works well with Cue's API. This example [2] is a swagger spec that was auto-generated entirely by the pecan-swagger plugin and fed into the Swagger UI.  I stood this up to primarily show the power and usefulness of Swagger.

While this works well and looks cool, I’m wondering if we can we do more. I’m not necessarily thinking about the official openstack doc sites, but about having a comprehensive specs for APIs, independent of our sites for now.

Here are the steps needed for solid swagger specs:

1. Generate swagger spec

Generating Swagger spec is what others and I have been working on, and a lot of tooling is already available.

2. Edit/confirm swagger spec
    (where i have questions, more info below)

3. Feed spec to UI (and more!)

Feeding the spec to a UI is relatively simple, since several projects exist that do this [3]. 

The missing piece that I’ve been thinking about lately is a sandboxy area to edit/confirm generated swagger specs (#2 above) and I’m wondering if anyone has a vision for what this should look like? I’ve heard of some ideas floating around but I would like to know more specifics.

I think getting some automation around generating swagger specs, and having a place where humans can confirm them would be a great start!  Let's worry about how they end up on docs sites later.


[1] https://github.com/elmiko/pecan-swagger
[2] http://15.126.235.36 
[3] https://github.com/russell/fairy-slipper/