<div dir="ltr"><br><div class="gmail_extra"><div class="gmail_quote">On Sat, Jul 6, 2013 at 9:16 AM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.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"><br><div class="gmail_extra"><br><div class="gmail_quote">

<div>I've been liking the Swagger API standard. Is there interest in investigating? </div>
<div><br></div><div><a href="https://github.com/wordnik/swagger-core/wiki" target="_blank">https://github.com/wordnik/swagger-core/wiki</a><br>

</div><div><div><br></div></div></div></div></div></blockquote><div><br></div><div>I've played with swagger a little bit for documenting an internal API. My impressions:</div><div><br></div><div>Pros:</div><div>- It produces very nice output</div>

<div>- The generated HTML/Javascript lets the user make REST calls directly from the browser.</div><div><br></div><div>Cons:</div><div>- The generated docs don't seem to distinguish query string parameters (that go in the url) and POST parameters (that go in the request body). This may not be an issue with the OpenStack API, but it was with the API I was documenting in the past.</div>

<div style>- Hand-editing the swagger JSON input isn't fun.</div><div style><br></div><div style>As long as we're automatically generating the JSON input from some other format, I think it's worth trying.</div>
<div style><br></div><div style><br></div><div style>Lorin</div><div style><br></div></div><div><br></div>-- <br><div dir="ltr">
Lorin Hochstein<br><div>Lead Architect - Cloud Services</div><div>Nimbis Services, Inc.</div><div><a href="http://www.nimbisservices.com" target="_blank">www.nimbisservices.com</a></div></div>
</div></div>