[openstack-dev] [docs] [api] Oh Swagger, where art thou?

Jim Rollenhagen jim at jimrollenhagen.com
Thu Mar 31 13:43:33 UTC 2016


On Thu, Mar 31, 2016 at 08:43:29AM -0400, Sean Dague wrote:
> Some more details on progress, because this is getting closer every day.
> 
> There is now an api-ref target on the Nova project. The entire work in
> progress stream has been rebased into 2 patches to a top level api-ref/
> directory structure in the Nova tree -
> https://review.openstack.org/#/q/status:open+project:openstack/nova+branch:master+topic:wip_api_docs2
> 
> That is a 2 patch series. The first is the infrastructure, the second is
> the content for 2 resources (versions and servers). The rendered output
> for this is at -
> http://docs-draft.openstack.org/63/298763/4/check/gate-nova-api-ref/6983838//api-ref/build/html/
> (you can also pull and build locally with tox -e api-ref)
> 
> Karen, Auggy, and Anne continue to work on the wadl data translator
> using the wadl2rst project and fairy-slipper to get various pieces of
> the structured data over. Hopefully we'll see some of those translated
> stacks rendering soon in patch sets.

I assume at some point we'll be pulling the sphinx extension out to a
separate project so that other projects can use this too? :)

// jim

> 
> 	-Sean
> 
> On 03/29/2016 07:56 AM, Sean Dague wrote:
> > Some additional links to what this sort of looks like right now -
> > http://docs-draft.openstack.org/71/298671/1/check/gate-nova-docs/c9e7f66//doc/build/html/rest_api/
> > 
> > Which is built off an RST file that looks like - http://tinyurl.com/hjqpjdm
> > 
> > The notable additions are the ".. rest_method::" stanza, which is what
> > provides the collapsing method sections (as are in the current api-ref
> > site).
> > 
> > As well as the ".. rest_parameters::" stanza which takes a list of
> > parameter names, and lookup keys to an external yaml file. This allows
> > for building the tables for these parameters much in the same way as the
> > existing WADL does but in a way where long for description can be easily
> > done. (Tables + rst are a bit cumbersome in the base case).
> > 
> > The #1 Goal here is better docs for Humans. In all cases today, Humans
> > are the primary consumers of our API, building software that uses. A
> > large number of the current API docs have inaccuracies or are generally
> > confusing because few people have been able to ventured into the WADL to
> > make more than small typographic changes.
> > 
> > Getting over to an RST base, that is content first in approach, will
> > hopefully open up the effort to more contributors.
> > 
> > Swagger is neat. But it's important to remember it's actually an API
> > Design Tool, which provides the benefit of some documentation tooling
> > around it. If used in the Design phase of an API it imposes a set of
> > constraints that help build a solid API. Retrofiting to swagger is at
> > best difficult, and some of the features our APIs use make it impossible.
> > 
> > This POC has mostly been about demonstrating what a content first
> > approach could be, where we could plug in structured / semi-structured
> > data via sphinx extensions. In phase 1, that will be our custom quick
> > and dirty markup format that's swagger inspired. In the future projects
> > could replace some of these plug points with other structured content in
> > their projects, like jsonschema / swagger / raml, whatever is appropriate.
> > 
> > However, we need to make sure we don't delay moving forward to get off a
> > WADL base until we've perfected any of those other approaches. We're
> > living on brownfield that is on fire. Getting to higher ground is
> > priority one. Iterating after we're there will continue to happen.
> > 
> > There is a cross project design summit session proposed for this work as
> > well, so we can show current status and discuss futures on this.
> > 
> > As always, comments and questions welcomed. Our giant etherpad of doom
> > in poking at this work, and what's been discovered is here -
> > https://etherpad.openstack.org/p/api-site-in-rst
> > 
> > 	-Sean
> > 
> > On 03/28/2016 06:21 PM, Anne Gentle wrote:
> >> Hi all,
> >>
> >> This release I’ve been communicating about moving from WADL to Swagger
> >> for the API reference information on developer.openstack.org
> >> <http://developer.openstack.org>. What we've discovered on the journey
> >> is that Swagger doesn't match well for our current API designs (details
> >> below), and while we're not completely giving up on Swagger, we're also
> >> recognizing the engineering effort to maintain and sustain those efforts
> >> isn't going to magically appear.
> >>
> >> Sean Dague has put together a proof-of-concept with Compute servers
> >> reference documentation to use Sphinx, RST, parameters files, and some
> >> Sphinx extensions to do a near-copy representation of the API reference
> >> page. We've met with the Nova API team, the API working group, and other
> >> interested developers to make sure our ideas are sound, and so far we
> >> have consensus on forging a new path forward. The review patch is here:
> >> https://review.openstack.org/#/c/292420.
> >>
> >> I believe we can still find uses for the Swagger migration for some
> >> projects that match the specification really well. We'll keep outputting
> >> the draft Swagger files to http://developer.openstack.org/draft/swagger/
> >> and continue to look for the use case for Swagger. Perhaps it's a
> >> try-it-out connection to TryStack. Maybe some projects will want to
> >> build clients from those files. We know it's useful, but need to focus
> >> efforts for now.
> >>
> >> We know that some OpenStack APIs cannot fit Swagger’s model. For
> >> example, Compute, File Storage, Bare Metal, and Block Storage (nova,
> >> manila, ironic, and cinder projects) have microversions enabled for
> >> updates to the request body as we continue to evolve the API definition,
> >> and Swagger has no mechanism to display the changes between
> >> microversions for end-users. As another example, Compute, Block Storage,
> >> File Storage, Databases, and Networks APIs (nova, cinder, manila, trove,
> >> and neutron projects) have an /actions resource that allows multiple
> >> differing request bodies.
> >>
> >> I'm writing this email to let you all know there's a new plan coming. We
> >> are using pieces of work from the past efforts to get the best outcome
> >> for sustainable, useful API documentation. The API Reference and WADL
> >> files will remain in the api-site repo until we have a new publishing
> >> job that we can use to flip the switch.
> >>
> >> We'll be writing a new specification as well as presenting at an
> >> upstream contributor's talk about Swagger as a standard:
> >> https://www.openstack.org/summit/austin-2016/summit-schedule/events/7723
> >> Once we get the publishing pipeline established, look for review
> >> proposals to your project repos to store API docs there rather than in
> >> api-site.
> >>
> >> We're going to reboot the migration and get off of WADL. Three cheers
> >> for that. If you’d like to work on these efforts, please stay tuned to
> >> the usual mailing list channels and if you are a docs or API working
> >> group liaison, please stay up-to-date with the plans. Review the
> >> upcoming specification, look for API docs patches in your repo, review
> >> those, and keep the efforts moving.
> >>
> >> I'll also attend this week's cross-project meeting to be available for
> >> any questions during open discussion.
> >>
> >> Thanks,
> >> Anne, who is going to find her copy of the Oh Brother, Where Art Thou
> >> soundtrack now
> >>
> >> --
> >> Anne Gentle
> >> Rackspace
> >> Principal Engineer
> >> www.justwriteclick.com <http://www.justwriteclick.com>
> >>
> >>
> >> __________________________________________________________________________
> >> OpenStack Development Mailing List (not for usage questions)
> >> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >>
> > 
> > 
> 
> 
> -- 
> Sean Dague
> http://dague.net
> 




> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev




More information about the OpenStack-dev mailing list