Open Stack

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 http://rackerlabs.github.io/wadl2swagger/openstack.html 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.


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].

> 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.

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.

So since WADL is an API definition format, there were three possible ways
to try to get a Swagger copy of the OpenStack APIs:
- Convert WADL to Swagger
- Extract Swagger from the OpenStack code or tests
- Write Swagger by hand

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.

I hope this project can help in one of two ways:
- A preview of what OpenStack Swagger would look like to start discussions
about best practices or APIs that are difficult to model in Swagger.
- 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.

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.

[1]: https://github.com/rackerlabs/wadl2swagger
[2]: http://rackerlabs.github.io/wadl2swagger/openstack.html
[3]:
https://blog.apigee.com/detail/a_design_first_approach_to_building_apis_with_swagger
[4]: https://github.com/swagger-api/swagger-spec#additional-libraries
[5]: https://github.com/rackerlabs/wadl2swagger/issues

On Wed, Jan 28, 2015 at 11:41 AM, Everett Toews <everett.toews at rackspace.com
> wrote:

> On Jan 18, 2015, at 9:25 PM, Jay Pipes <jaypipes at gmail.com> wrote:
>
> > On 01/13/2015 07:41 AM, Sean Dague wrote:
> >> On 01/09/2015 04:17 PM, Everett Toews wrote:
> >>> One thing that has come up in the past couple of API WG meetings
> >>> [1] is just how useful a proper API definition would be for the
> >>> OpenStack projects.
> >>>
> >>> By API definition I mean a format like Swagger, RAML, API
> >>> Blueprint, etc. These formats are a machine/human readable way of
> >>> describing your API. Ideally they drive the implementation of both
> >>> the service and the client, rather than treating the format like
> >>> documentation where it’s produced as a by product of the
> >>> implementation.
> >>>
> >>> I think this blog post [2] does an excellent job of summarizing the
> >>> role of API definition formats.
> >>>
> >>> Some of the other benefits include validation of
> >>> requests/responses, easier review of API design/changes, more
> >>> consideration given to client design, generating some portion of
> >>> your client code, generating documentation, mock testing, etc.
> >>>
> >>> If you have experience with an API definition format, how has it
> >>> benefitted your prior projects?
> >>>
> >>> Do you think it would benefit your current OpenStack project?
> >>
> >> It would hugely benefit OpenStack to have this clear some where that
> >> was readable.
> >>
> >> I don't specifically have experience with these, my only feedback
> >> would be make sure whatever format supports having multiple examples
> >> per API call referenced or embedded.
> >>
> >> My experience is that API specs aren't typically fully read and
> >> injested. Instead examples are used to get some minimum working
> >> code, then bits are spot referenced and evolved until the client code
> >> looks like it does what was expected. So providing multiple examples
> >> per API will help more people wrap their head around the interface in
> >> question.
>
> 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).
>
> 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.
>
> 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.
>
> > This is spot-on, Sean.
> >
> > 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.
> >
> > Best,
> > -jay
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150128/c09f3d52/attachment.html>