<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On 14 July 2015 at 03:45, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<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 class="gmail_extra"><div class="gmail_quote"><div><div class="h5"><div><br></div></div></div><div><div>So I know it doesn't look like I've been doing anything but I have been trying to figure out JSON schema and fairy-slipper. :) I also went ahead and merged the spec since we have a good plan and can update it as needed from here on.</div></div></div></div></div></blockquote><div><br></div><div>Good stuff,  I have literally been doing nothing for the past week.</div><div><br></div><div>Current status:</div><div>- reasonably complete RST description of the API.  I think that the only thing not being translated is some of the formatting (numbered list for example) <a href="http://fairy-slipper.russellsim.org/rst/">http://fairy-slipper.russellsim.org/rst/</a></div><div>- prototype webserver but it doesn't render to JSON all the attributes that are needed.</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 class="gmail_extra"><div class="gmail_quote"><div><div>For one task, which is creating a JSON Schema we can use to validate the output, I think I need to study this line:</div><div><a href="https://github.com/russell/fairy-slipper/blob/master/tools/wadl_to_swagger.py#L448" target="_blank">https://github.com/russell/fairy-slipper/blob/master/tools/wadl_to_swagger.py#L448</a></div></div></div></div></div></blockquote><div><br></div><div>One unfortunate thing that has happened during the course of development is that I have had to compromise on the contents of the intermediate Swagger file.  As I started to develop the RST files i found that i needed other data to be included to make generation easier.  As a result the current Swagger files include more changes than I have described previously.<br></div><div><br></div><div>Yes we should be able to take the upstream swagger schema and modify it to include all the changes i described in that other email,  if you can do that I should be able to write a functional test that validates the output of the webserver against it.  That would be really helpful.  At the moment I have zero tests, it's sad :(</div><div><br></div><div><br></div><div>That line you have identified basically adds reference to an embedded JSONSchema description that will be located in the definitions section (JSON object key) of the Swagger file, it's a normal part of swagger.  It's always add but not always used.  In the case where there is no schema I trim this element,  this happens when converting to RST.</div><div><br></div><div>But 3 lines above is the 'method' key, this is new.  The list stuff is stored in a local dict on the class called self.apis it is keyed to the URLs and the value is [ ] and extended gradually as new self.current_api objects are created. <a href="https://github.com/russell/fairy-slipper/blob/master/tools/wadl_to_swagger.py#L473">https://github.com/russell/fairy-slipper/blob/master/tools/wadl_to_swagger.py#L473</a>  <a href="https://github.com/russell/fairy-slipper/blob/master/tools/wadl_to_swagger.py#L438">https://github.com/russell/fairy-slipper/blob/master/tools/wadl_to_swagger.py#L438</a></div><div><br></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 class="gmail_extra"><div class="gmail_quote"><div><div>then write a JSON Schema file that is identical to the Swagger 2.0 spec except for allowing an array for GET and POST and then moving the resources. Is that correct? Should I do a PR to the fairy-slipper repo with a JSON Schema file? I was thinking I'd put it in /tools then we can validate against it if needed.</div><div><br></div><div>Also I attended the nova team's API meeting last week and they are excited to help. </div></div></div></div></div></blockquote><div><br></div><div>Yes!  That would be great!  I'm going to squash the current commits and start using proper commit messages tonight.  Just push when ever you like.</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 class="gmail_extra"><div class="gmail_quote"><span class=""><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 class="gmail_extra"><div class="gmail_quote"><div></div><div>I am curious about how the migration will work:</div><div>When this is proposed as a patch will we delete the WADL files immediately?  or will they hang around?  </div></div></div></div></blockquote><div><br></div></span><div>I'd love to delete the WADL files as a patch that depends on the patch that replaces it all. They'll be retrievable in the git log if we ever need them "one day." I'm good with that.</div></div></div></div></blockquote><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 class="gmail_extra"><div class="gmail_quote"><span class=""><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 class="gmail_extra"><div class="gmail_quote"><div>Perhaps we could use a feature branch?  That way the OPs team can have a chance to prep the <a href="http://openstack.org" target="_blank">openstack.org</a> website for the transition and we can maintain the WADL files until we are ready to launch?</div></div></div></div></blockquote><div><br></div></span><div>A feature branch is exactly what we can do (or the dependent branch I mentioned above). </div><div><br></div><div>I was targeting <a href="http://developer.openstack.org" target="_blank">developer.openstack.org</a> for the content, and the current job is a file copy through FTP. So to prepare <a href="http://developer.openstack.org" target="_blank">developer.openstack.org</a> I guess we'll need the web server ready? It's currently Cloud Sites on Rackspace if my memory serves. We'll need to get a real web server. Can you describe the specs, as in, what would the implementation require? We'd probably need to puppet-ize the build? Hopefully Infra-team can offer us input.</div></div></div></div></blockquote><div><br></div><div>Cool,  Currently it's hosted on the smallest VM that Rackspace offers.  I'm still working on getting the webserver into a state where it can replace the static files, once that is done we can look making a puppet module.</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 class="gmail_extra"><div class="gmail_quote"><span class=""><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 class="gmail_extra"><div class="gmail_quote"><div>What are we going to do about the frontend?  That is an area that will require some thought about how to present the information.  I personally don't like either example above.  I don't like the current API doc, too much scrolling, no navigation.  jensoleg's is crap because of too much scrolling, also features confusing amounts of scrolling for large response examples.  The default swagger interface sucks because it assumes I am a robot?  why is the URL more important that what the URL does?  Basically i think we can do better.  I think this is probably the best interface for API documentation i have seen so far <a href="http://docs.apimatic.apiary.io/" target="_blank">http://docs.apimatic.apiary.io/</a> but if people can suggest other sites we can draw ideas from that would be great.</div></div></div></div></blockquote><div><br></div></span><div>Agreed on the large response examples from jensoleg's Stripe example but I like the side-by-side (and Apiary does something similar). At Rackspace we are working on new layouts as well, so maybe we could work together on interfaces, let me know and I'll connect you.</div><div><br></div></div></div></div></blockquote><div><br></div><div>Yep,  once I get the webserver off the ground.  I'll start creating a layout,  I'm guessing that it will probably be a mix of all the layouts listed above.  But it will not allow the size of the examples to affect the page scroll.  I do like the 3 column layout though.  I'll see what I can prototype and then I'll have a look at the new Rackspace doc layout.</div></div><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr">Cheers,<br>Russell Sim</div></div>
</div></div>