On Thu, Aug 20, 2015 at 7:58 PM, Melnik, Aleksandr S < aleksandr.s.mel...@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-d...@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -- Anne Gentle Rackspace Principal Engineer www.justwriteclick.com
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
