<div dir="ltr">tl;dr: I wanted to be able to see what OpenStack APIs might look like in Swagger and starting experimenting with Swagger in projects for things like stubbing services, API test coverage, and code generation. In order to do that I created wadl2swagger [1]. I've published copies [2] of what the converted documents look like. If you follow the "Open on Swagger-Editor" links at <a href="http://rackerlabs.github.io/wadl2swagger/openstack.html">http://rackerlabs.github.io/wadl2swagger/openstack.html</a> you can open the Swagger-equivalent of any WADL file and see both the source and a preview of what Swagger-generated documentation would look like.<div><br><div><br></div><div>I definitely agree that moving to a better API definition would be very beneficial. Technically WADL *is* an API definition format, it's just not one that's very usable or that has an active community (with the exception of documentation, and even that is probably mostly only OpenStack). I think it's partly because WADL was created during a transitional period - services were tending towards REST but not yet towards JSON - but I think that Apigee summed it up nicely when they created the Swagger Editor [3].</div><div><br></div><div>> WSDL and WADL failed to cross languages and therefore developer communities, but Swagger has thrived, with community contributions easily outnumbering those from the team at Reverb.</div><div><br></div><div>Check out the list of related projects for Swagger [4] to verify that for yourself. Not only are there *actively developed* projects in many different programming languages, the projects also target a wide range of problems, from extracting documentation from code to testing or code generation. I think that's especially true of Swagger, though you could say the same thing about RAML. However, the Swagger/RAML gap is much smaller than the WADL/Swagger gap, and there's already a swagger2raml project underway, so converting data from WADL to Swagger seems like a good move even if RAML is still being considered.</div><div><br></div><div>So since WADL is an API definition format, there were three possible ways to try to get a Swagger copy of the OpenStack APIs:</div><div>- Convert WADL to Swagger</div><div>- Extract Swagger from the OpenStack code or tests</div><div>- Write Swagger by hand</div><div><br></div><div>I focused on the first approach, merging in a little bit of hand-written Swagger from the third approach to cover data that I wanted in Swagger but that isn't available in the WADL. The second approach may also be worth pursuing, especially if the data we can get from WADL and the data we can get from code/tests are complimentary. The WADL is good at converting the routing, parameters, request/response examples, general documentation and expected response codes, but it isn't easy to get request/response body schemas.</div><div><br></div><div>I hope this project can help in one of two ways:<br></div><div>- A preview of what OpenStack Swagger would look like to start discussions about best practices or APIs that are difficult to model in Swagger.</div><div>- As an actually tool to enable a WADL->Swagger transition or to compare to Swagger from other sources to ensure the documentation/implementation are in sync.</div><div><br></div><div>If you just take these documents as a draft than there's no need to look at the code, but if you want to use and improve the tool then I need some help maintaining the project. It probably makes sense to clean up the project before doing any more enhancements, because it started as a spike and is my first non-trivial Python project, so the code is undoubtedly sloppy. However it's fairly small (543 lines of Python) so cleaning it up probably isn't a huge undertaking. Please let me know or check out the issues on GitHub [5] if you're interested in helping clean with the project.</div><div><br></div><div>[1]: <a href="https://github.com/rackerlabs/wadl2swagger">https://github.com/rackerlabs/wadl2swagger</a></div><div>[2]: <a href="http://rackerlabs.github.io/wadl2swagger/openstack.html">http://rackerlabs.github.io/wadl2swagger/openstack.html</a></div><div>[3]: <a href="https://blog.apigee.com/detail/a_design_first_approach_to_building_apis_with_swagger">https://blog.apigee.com/detail/a_design_first_approach_to_building_apis_with_swagger</a></div><div>[4]: <a href="https://github.com/swagger-api/swagger-spec#additional-libraries">https://github.com/swagger-api/swagger-spec#additional-libraries</a></div><div>[5]: <a href="https://github.com/rackerlabs/wadl2swagger/issues">https://github.com/rackerlabs/wadl2swagger/issues</a></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jan 28, 2015 at 11:41 AM, Everett Toews <span dir="ltr"><<a href="mailto:everett.toews@rackspace.com" target="_blank">everett.toews@rackspace.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Jan 18, 2015, at 9:25 PM, Jay Pipes <<a href="mailto:jaypipes@gmail.com">jaypipes@gmail.com</a>> wrote:<br>
<br>
> On 01/13/2015 07:41 AM, Sean Dague wrote:<br>
>> On 01/09/2015 04:17 PM, Everett Toews wrote:<br>
>>> One thing that has come up in the past couple of API WG meetings<br>
>>> [1] is just how useful a proper API definition would be for the<br>
>>> OpenStack projects.<br>
>>><br>
>>> By API definition I mean a format like Swagger, RAML, API<br>
>>> Blueprint, etc. These formats are a machine/human readable way of<br>
>>> describing your API. Ideally they drive the implementation of both<br>
>>> the service and the client, rather than treating the format like<br>
>>> documentation where it’s produced as a by product of the<br>
>>> implementation.<br>
>>><br>
>>> I think this blog post [2] does an excellent job of summarizing the<br>
>>> role of API definition formats.<br>
>>><br>
>>> Some of the other benefits include validation of<br>
>>> requests/responses, easier review of API design/changes, more<br>
>>> consideration given to client design, generating some portion of<br>
>>> your client code, generating documentation, mock testing, etc.<br>
>>><br>
>>> If you have experience with an API definition format, how has it<br>
>>> benefitted your prior projects?<br>
>>><br>
>>> Do you think it would benefit your current OpenStack project?<br>
>><br>
>> It would hugely benefit OpenStack to have this clear some where that<br>
>> was readable.<br>
>><br>
>> I don't specifically have experience with these, my only feedback<br>
>> would be make sure whatever format supports having multiple examples<br>
>> per API call referenced or embedded.<br>
>><br>
>> My experience is that API specs aren't typically fully read and<br>
>> injested. Instead examples are used to get some minimum working<br>
>> code, then bits are spot referenced and evolved until the client code<br>
>> looks like it does what was expected. So providing multiple examples<br>
>> per API will help more people wrap their head around the interface in<br>
>> question.<br>
<br>
In my experience developing client tools for OpenStack for the past 2 years, the examples are useful but, sooner rather than later, I find myself needing the full API definition (I’m avoiding the word spec because it’s overloaded in OpenStack land already).<br>
<br>
The reason the OpenStack API examples are so useful is because they include details that really should be part of the definition. So often I find myself looking at an example and wondering where a param came from and its possible range of values only to find no mention of that param in the definition.<br>
<br>
I’m definitely +1 to multiple examples per API but those examples need to be built on top of proper API definitions. I’d like to see us move away from an API documentation second mindset to an API definition first mindset. Having the API definition drive the implementation of the client and the service.<br>
<br>
> This is spot-on, Sean.<br>
><br>
> I would support making Swagger the API definition format for OpenStack APIs. I think it's by far the best of the bunch, in my experience, and I've used API Blueprint, Swagger, and RAML.<br>
><br>
> Best,<br>
> -jay<br>
<br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote></div><br></div>