<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On Sat, Jun 27, 2015 at 10:43 PM, Russell Sim <span dir="ltr"><<a href="mailto:russell.sim@gmail.com" target="_blank">russell.sim@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><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/" target="_blank">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/" target="_blank">http://fairy-slipper.russellsim.org/swagger-ui-jensoleg/</a><br></div><div><br></div></div></div></blockquote><div><br></div><div>Super excited about your progress and proof of concept!<br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><div></div><div>Raw swaggerish files <a href="http://fairy-slipper.russellsim.org/" target="_blank">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/" target="_blank">https://review.openstack.org/#/c/195364/</a><br></div><div><a href="https://review.openstack.org/#/c/196407/" target="_blank">https://review.openstack.org/#/c/196407/</a><br></div><div><br></div></div></div></blockquote><div><br></div><div>Both merged, cool.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><div></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></div></blockquote><div><br></div><div>Heh, it's a lot to document any way you look at it. </div><div><br></div><div>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:</div><div><a href="http://developer.openstack.org/api-ref-orchestration-v1.html#stack_action_suspend">http://developer.openstack.org/api-ref-orchestration-v1.html#stack_action_suspend</a> <br></div><div><a href="http://developer.openstack.org/api-ref-orchestration-v1.html#stack_action_resume">http://developer.openstack.org/api-ref-orchestration-v1.html#stack_action_resume</a><br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><div></div><div>The code repository I'm using is <a href="https://github.com/russell/fairy-slipper" target="_blank">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></div></blockquote><div><br></div><div>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)? </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><div>- Convert Swaggerish into ReST/JSONSchema (started, but nowhere near complete)</div></div></div></blockquote><div><br></div><div>Where should the JSON Schema live, in the fairy-slipper repo for now??</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><div>- Write webserver to render ReST/JSONSchema to Swaggerish (started, but nowhere near complete)</div></div></div></blockquote><div><br></div><div>Anyone interested in this one?</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><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></div></blockquote><div><br></div><div>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?</div><div><a href="http://developer.openstack.org/api-ref-compute-v2.html#compute_servers">http://developer.openstack.org/api-ref-compute-v2.html#compute_servers</a><br></div><div><br></div><div>If it's something else, let me know. </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><div></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" target="_blank">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></div></blockquote><div><br></div><div>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? </div><div><br></div><div>I'll update the spec at <a href="https://review.openstack.org/#/c/177934/">https://review.openstack.org/#/c/177934/</a> and merge it pretty quickly as I think the approach is sound and we should start dividing the work as we can.</div><div><br></div><div>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!</div><div>Thanks,</div><div>Anne</div><div><br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><div><br></div><div>Any feedback is welcome.</div><span class=""><font color="#888888"><div><br></div>-- <br><div><div dir="ltr">Cheers,<br>Russell Sim</div></div>
</font></span></div></div>
<br>_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>