<div dir="ltr">Hi,<div><br></div><div>I have been working to try and create new implementation of the API reference based of Swagger.</div><div><br></div><div>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.</div><div><br></div><div>Default Swagger UI <a href="http://fairy-slipper.russellsim.org/swagger-ui/">http://fairy-slipper.russellsim.org/swagger-ui/</a><br></div><div><div>jensoleg's Swagger UI <a href="http://fairy-slipper.russellsim.org/swagger-ui-jensoleg/">http://fairy-slipper.russellsim.org/swagger-ui-jensoleg/</a><br></div><div><br></div><div>Raw swaggerish files <a href="http://fairy-slipper.russellsim.org/">http://fairy-slipper.russellsim.org/</a> you can copy and paste the urls into the swagger UI's above to view them.</div><div><br></div><div>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.</div><div><a href="https://review.openstack.org/#/c/195364/">https://review.openstack.org/#/c/195364/</a><br></div><div><a href="https://review.openstack.org/#/c/196407/">https://review.openstack.org/#/c/196407/</a><br></div><div><br></div><div>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. :(</div><div><br></div><div>The code repository I'm using is <a href="https://github.com/russell/fairy-slipper">https://github.com/russell/fairy-slipper</a> 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.</div><div><br></div><div>What's next.</div><div>- Improve the Docbok/WADL parsers, so that it picks up the methods that are currently missing.</div><div>- Convert Swaggerish into ReST/JSONSchema (started, but nowhere near complete)</div><div>- Write webserver to render ReST/JSONSchema to Swaggerish (started, but nowhere near complete)</div><div>- 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)</div><div><br></div><div>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 <a href="http://openstack.org">openstack.org</a> 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.</div><div><br></div><div>Any feedback is welcome.</div><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr">Cheers,<br>Russell Sim</div></div>
</div></div>