<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Aug 20, 2015 at 7:58 PM, Melnik, Aleksandr S <span dir="ltr"><<a href="mailto:aleksandr.s.melnik@hp.com" target="_blank">aleksandr.s.melnik@hp.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">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.<br>
<br>
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.<br>
<br>
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.<br>
<br>
Here are the steps needed for solid swagger specs:<br>
<br>
1. Generate swagger spec<br>
<br>
Generating Swagger spec is what others and I have been working on, and a lot of tooling is already available.<br>
<br>
2. Edit/confirm swagger spec<br>
(where i have questions, more info below)<br>
<br>
3. Feed spec to UI (and more!)<br>
<br>
Feeding the spec to a UI is relatively simple, since several projects exist that do this [3].<br>
<br>
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.<br>
<br>
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.<br></blockquote><div><br></div><div>Thanks for this Aleksandr. We've had a spec at <a href="http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html" target="_blank">http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html</a> 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. </div><div><a href="http://lists.openstack.org/pipermail/openstack-docs/2015-August/007347.html">http://lists.openstack.org/pipermail/openstack-docs/2015-August/007347.html</a></div><div>We would love your Swagger knowledge to add to our efforts. </div><div><br></div><div>I've also got API doc guidelines in the API working group that I'd like you to review <a href="https://review.openstack.org/#/c/214817/">https://review.openstack.org/#/c/214817/</a></div><div><br></div><div>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.</div><div><br></div><div>Thanks,</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
<br>
[1] <a href="https://github.com/elmiko/pecan-swagger" rel="noreferrer" target="_blank">https://github.com/elmiko/pecan-swagger</a><br>
[2] <a href="http://15.126.235.36" rel="noreferrer" target="_blank">http://15.126.235.36</a><br>
[3] <a href="https://github.com/russell/fairy-slipper/" rel="noreferrer" target="_blank">https://github.com/russell/fairy-slipper/</a><br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>