RAML or Swagger 2


#1

Hey all,

I am wondering if the RAML spec (1.0) and modules and such are slowing down or if there is anything on the horizon to speak of? I am looking to use RAML, but thought by now the 1.0 would be out and that there would be a lot more development activity around the spec and tools. A fellow colleague came to me today and brought up using Swagger 2, and at first I thought RAML was far ahead, but looking at the Swagger site… they have a lot of stuff going on. They seem to have far more modules for more languages, although I’ll be honest and saying I haven’t looked into whether or not they are all updated Swagger 2 or not.

But I am not trying to make RAML look bad…I think it’s great. My concern is I may be tasked with building out our API doc, sdk, cli and other areas, and I’ve been betting on RAML, but with others looking at Swagger and it’s popularity, I am lacking a good argument for either side. Can any of you offer a few reasons why RAML would be the better way to go vs Swagger 2? We’ll mostly be looking to capitalize on a “single source of truth” document that we then use to generate server side JAX-RS (and possibly Spring and Scala…which RAML lacks both but Swagger 2 has work going on in those areas), as well as client side SDKs and CLIs that use the generate SDKs. As well, good documentation for our consuming developers to use to figure out our APIs.

Thoughts?


#3

Hi @justjacksonn,

Thanks for your post and trying to understand what is going on with RAML before going away completely :wink: We are aware of what Swagger 2.0 offers right now and some of the limitation compared to RAML (see http://forums.raml.org/t/how-is-this-different-from-swagger/24/7 - where you actually have been posting something as well :wink: ).

We are in a process of improving the experience with RAML introducing 1.0 very soon and various improvements to this web sites and tools around RAML. The RAML community and developers are taking ideas from someone like you and other people very serious and trying to implements them into RAML or working with different parties to develop the tools to help you to design and build robust APIs, and bring the best experience also to the documentation piece. BUT to achieve that we and the developers of the tooling around RAML needs feedback from our lovely community. :wink:

I don’t want to add something on RAML vs Swagger 2.0 as this was discussed a lot in the post I linked before, but RAML 1.0 introduce a lot feature which you mentioned like modules. We created a project to generate clients (see https://github.com/mulesoft/raml-client-generator) using templates and have people working on different languages. We get more and more parser for different languages where the newest one is Go. There is a lot going on in the background and if you look on Github, there are more than 150 (my last check ^^) projects with a RAML topic. We just reach our 1.0 milestone where Swagger was 4 years ago with their first release. Taking that in consideration - RAML already grow really good and found a lot attraction within the developer/api community as well.

The last thing I want to say is really that I am someone who want to avoid feature comparison as we only can speak or refer of them ‘as of today’. You never know what is coming in couple of days or month or etc. right?

What I’ll also take out from your comment is that we as the community and the people behind should think of creating more visibility what happens behind the scenes, but I would love to hear more what you think would be nice to have besides the usual tooling etc. as we can hardly control it :wink:

Hope others share my view and add more comments as I think that is a great discussion.

Thanks again!

Cheers,
Christian