Open Stack

On Sat, Jun 27, 2015 at 10:43 PM, Russell Sim <russell.sim at gmail.com> wrote:

> 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/
>
>
Super excited about your progress and proof of concept!



> 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/
>
>
Both merged, cool.


> 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. :(
>
>
Heh, it's a lot to document any way you look at it.

But it's cool you got the multiple request/response worked out. An example
for those who are reading along is the Orchestration actions resource:
http://developer.openstack.org/api-ref-orchestration-v1.html#stack_action_suspend

http://developer.openstack.org/api-ref-orchestration-v1.html#stack_action_resume



> 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.
>

I want to help with this, is the best way to side-by-side compare the
output with the current WADL (or HTML output from WADL)?


> - Convert Swaggerish into ReST/JSONSchema (started, but nowhere near
> complete)
>

Where should the JSON Schema live, in the fairy-slipper repo for now??


> - Write webserver to render ReST/JSONSchema to Swaggerish (started, but
> nowhere near complete)
>

Anyone interested in this one?


> - 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'd like to pull out the descriptive info into RST files or some such. I'm
guessing it's text like what's in the Servers info here?
http://developer.openstack.org/api-ref-compute-v2.html#compute_servers

If it's something else, let me know.


> 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.
>

Yep, I'm good with this approach. Should we patch the openstack/api-site
repo in the interim for testing purposes? Or just leave it in fairy-slipper
while we keep working?

I'll update the spec at https://review.openstack.org/#/c/177934/ and merge
it pretty quickly as I think the approach is sound and we should start
dividing the work as we can.

Thanks so much for working on this! I know we can share some tasks so it
doesn't feel like you're eating an elephant!
Thanks,
Anne




>
> Any feedback is welcome.
>
> --
> Cheers,
> Russell Sim
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


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