Open Stack

Hi all,
In working on this spec [1] to replace the WADL-built API references with
Swagger-built API references, I found a possible interim solution that
builds flat HTML files from Swagger. [2] So, instead of using swagger-ui
running on a web server, we could write a script to build one HTML file per
service, much like the current WADL scripts do.

Then, we continue working on fairy-slipper to best display both reference
data and how-to/concept information together.

As an idea of what I would consider "code complete" for the migration:
1. All services WADL files migrate without any errors in the
gate-build-swagger
<http://logs.openstack.org/57/281657/1/check/gate-build-swagger/993145e/> job.
Currently the Networking API files have the most errors and the team is
looking into it. I've been logging bugs when the tool finds errors when
migrating WADL.
2. All current HTML pages on developer.openstack.org/api-ref.html can be
redirected.

However, defining "good enough" for the fairy-slipper display and
interaction piece is more complex. So I believe an interim solution that
migrates the WADL and gets off of WADL and clouddocs-maven-plugin for
builds is a good way forward.

What do you all think? Karen, Russell, and Mike McCune I'd definitely like
your input.

Thanks,
Anne


1. https://review.openstack.org/#/c/276484/
2. https://github.com/nknapp/bootprint-openapi

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