Open Stack

On Thu, Aug 20, 2015 at 7:58 PM, Melnik, Aleksandr S <
aleksandr.s.melnik at hp.com> wrote:

> 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.
>

Thanks for this Aleksandr. We've had a spec at
http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html
we're
working on this release to do all these, and fairy-slipper is where we're
working. I just sent a note to the openstack-docs mailing list with
updates.
http://lists.openstack.org/pipermail/openstack-docs/2015-August/007347.html
We would love your Swagger knowledge to add to our efforts.

I've also got API doc guidelines in the API working group that I'd like you
to review https://review.openstack.org/#/c/214817/

As for confirming the Swagger spec (2) for new projects, I'm open to ideas.
We've had to modify the Swagger 2.0 spec to accommodate existing known
non-conforming REST APIs such as Compute and Orchestration API sending
multiple request bodies to /actions resource. I think the way forward is
WADL to Swagger conversion to detect any drift in current reference and
then ensure that the Swagger output is updated with any patchset to the
code. For non-pecan WSGI frameworks we'll need a tool to create those.

Thanks,
Anne


>
>
> [1] https://github.com/elmiko/pecan-swagger
> [2] http://15.126.235.36
> [3] https://github.com/russell/fairy-slipper/
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150820/a1fe2652/attachment.html>