Open Stack

Hi,

I have been working to try and create new implementation of the API
reference based of Swagger.

I have enough of the conversion completed to create an initial prototype of
the Swaggerish JSON that can be used in a modified swagger-js client.  None
of the interactive client parts work because I don't have a devstack on the
host with CORS configured and the Swagger client doesn't know how to pass a
token to the keystone middleware.

Default Swagger UI http://fairy-slipper.russellsim.org/swagger-ui/
jensoleg's Swagger UI
http://fairy-slipper.russellsim.org/swagger-ui-jensoleg/

Raw swaggerish files http://fairy-slipper.russellsim.org/ you can copy and
paste the urls into the swagger UI's above to view them.

I have picked up some inconsistencies in the WADL files that I have been
gradually fixing these. The following 2 outstanding reviews are all that's
needed to fix things well enough to make the dumb converter that I've
written work.
https://review.openstack.org/#/c/195364/
https://review.openstack.org/#/c/196407/

I keep saying Swaggerish, because the swagger output isn't actually
swagger, it's modified to support multiple request/response types at the
same URL.  Basically, because the OpenStack API isn't really REST. :(

The code repository I'm using is https://github.com/russell/fairy-slipper
but beware, the code is a disgrace.  I tried using a proper WADL parser,
but I couldn't get it to work, so instead I have a horrid SAX based parser
that drunkenly fumbles through the files trying really hard not to crash.

What's next.
- Improve the Docbok/WADL parsers, so that it picks up the methods that are
currently missing.
- Convert Swaggerish into ReST/JSONSchema (started, but nowhere near
complete)
- Write webserver to render ReST/JSONSchema to Swaggerish (started, but
nowhere near complete)
- Update Swagger UI to include Tag documentation. (currently swagger has no
understanding of the documentation at the top of each chapter.  It's
included in the swaggerish files but it's not rendered in the client
presently)

I originally had really high hopes of converting the doc and pushing it
into the OpenStack services, I've scoped this back a bit initially because
I think it would be better to convert the current documentation into the
new formats first.  We will need a way to host this on the openstack.org
website which may not have access to a running OpenStack deployment.  Once
I have this in a form that is acceptable, then I'll look at how this will
be best integrated the documentation into each of the OpenStack services.

Any feedback is welcome.

-- 
Cheers,
Russell Sim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150628/0f4659e9/attachment.html>