Open Stack

On Sat, Jul 6, 2013 at 9:16 AM, Anne Gentle
<annegentle at justwriteclick.com>wrote:

>
>
> I've been liking the Swagger API standard. Is there interest in
> investigating?
>
> https://github.com/wordnik/swagger-core/wiki
>
>
I've played with swagger a little bit for documenting an internal API. My
impressions:

Pros:
- It produces very nice output
- The generated HTML/Javascript lets the user make REST calls directly from
the browser.

Cons:
- 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.
- Hand-editing the swagger JSON input isn't fun.

As long as we're automatically generating the JSON input from some other
format, I think it's worth trying.


Lorin


-- 
Lorin Hochstein
Lead Architect - Cloud Services
Nimbis Services, Inc.
www.nimbisservices.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130706/2573bf1c/attachment.html>