RAML vs. Swagger vs. API Blueprint

At Glue Conference I had the awesome chance to learn about more great API design and documentation tools, including Swagger headed up by Reverb and API Blueprint headed up by Apiary. With multiple options available for API Design and documentation I wanted to take a more in-depth look to see how they all compared. Please keep in mind this is a quick glance of these different technologies, so please if you find something that isn’t right- let me know. Otherwise, here’s what I found!

Community (based on GitHub):

Overview: Swagger by far has the largest and most active developer community. However, it is also important to note that it is the oldest being released in July 2011, while API Blueprint and RAML are both relative new comers with API Blueprint being released May 2013, and RAML the baby of the three being released in October 2013. Adjusting for age differential (assuming continuous growth based on today’s numbers), API Blueprint would take the watching (308) and forked (1026) categories, while RAML would take the starred (2556) category.

Winner: Swagger by a landslide

Industry Backing:

Overview: While I believe all three standards were created with the best of intentions and highly influenced by the industry, RAML, while backed strongly by MuleSoft (an API management company) is also backed by leaders in the API industry who are helping to shape and form it’s direction.

Winner: RAML by a landslide

Website Ease of Use:

Overview: Both API Blueprint and RAML provide intuitive, easy to use websites that help you get started quickly while locating the projects that best serve your needs. Swagger’s site however is really nothing more than a landing page on Reverb forcing to dig through different resources to find their Wiki, Projects, and Repos.

Winner: Tie (RAML & API Blueprint)

Writing Spec:

Overview: While many developers may prefer the JSON format, RAML makes it easy for developers and non-developers alike to read and update the RAML spec. This makes it perfect for designing an API from the ground up, or for your documentation team to help keep it up to date/ make the documentation more readable.

Ease of Getting Started:

Overview: From my personal experience I found RAML very easy to get setup with. While API Blueprint has a very intuitive site, it requires numerous steps to get in the “writing stage,” and while Swagger provides everything in Github repos, its lack of an intuitive site makes getting started difficult and requires a bit of Googling. RAML on the other hand not only provides quick, easy to understand documentation and live demos, but quick access to the different GitHub repos with clear, non-technical explanations of what each project does.

Winner: RAML

API Builder:

Overview: While RAML may be the easiest to build an API from when using Mule Studio with API Kit and a server supporting Mule (allowing you to drag and drop different services/ connect to different endpoints), I was extremely impressed with the numerous tools Swagger provides for building your API using their spec. Swagger has tools for nearly every language and allows you to deploy server instances to get your API up and running. The numerous tools, along with greater flexibility gives Swagger the clear win on this one.

Winner: Swagger

API Console:

RAML: Grouped by endpoint with drill down into verbs
Swagger: Every HTTP Action Verb is separate
API Blueprint: Unknown

Overview: Both RAML and Swagger provide intuitive easy to read and use API Consoles to allow developers to interact with your API. However, the overall design flow of RAML’s console is more intuitive as it groups endpoints together allowing developers to select the HTTP Action Verb they want to research/ try out, instead of creating a new section for each action verb – this helps separate the endpoints and makes it easier for developers to find what they are looking for. RAML also provides a very intuitive API Notebook allowing developers to tinker with your API and even test it out in conjunction with other public, RAML supported APIs.

Winner: RAML

Documentation Builder:

Overview: Both API Blueprint and RAML give you the option to build single or multipage documentation, however the multipage script for RAML is only available in PHP, and API Blueprint gives you more options with a slightly nicer single page documentation layout. That means API Blueprint just edges out RAML on this one.

Winner: API Blueprint

Language Support:

Overiew: Both RAML and Swagger support the most popular languages, however Swagger goes above and beyond by supporting Clojure, Go, and Scala. The biggest differentiator I see between the two, however is the lack of .NET support in RAML, helping to make Swagger the clear winner in this case while API Blueprint gets left in the dust appearing to offer minimal language support.

Winner: Swagger

Overall Tallies:

RAML: 6 wins
Swagger: 4 wins
API Blueprint: 2 wins

Overview: Each project brings different strengths and weaknesses to the table, and in the end it’s really about what strengths you need, and which weaknesses you cannot afford. Overall, RAML fared the best in these different categories, and while the developer community is not as large as the others I think it’s safe to say it will keep growing.

Overall Winner: RAML

Disclaimer: I work for MuleSoft, a major contributor to RAML. However, this post is intended to be as unbiased as possible, stepping outside of the “MuleSoft” role, and back into Mike the programmer to find out what solution does what best. It is also important to note that these are my PERSONAL thoughts and views based on my own research and in no way reflect the views or thoughts of MuleSoft or any of the companies listed.

23 Responses to “RAML vs. Swagger vs. API Blueprint”

That is absolutely correct. The community analytics were strictly focused on the current core repositories for API Blueprint, RAML, and Swagger. I didn’t include Swagger 2 as it is still in development and as such stating its capabilities would be purely hypothetical at this point (like the iPhone 6). What I do know is that Swagger2 will be incorporating an API design-first philosophy and will switch from JSON to YAML (which raises the question of backwards compatibility with the scripts that are in existence today). To try and state what the Swagger2 community will look like at this juncture is extremely premature in my opinion.

Absolutely agree! There is an obvious bias, not because I work for MuleSoft, but because I personally like RAML (despite having used Swagger in the past).

That’s why I created the categories and judging criteria before even evaluating any of the specs against them. In other words, I had no idea which spec would win which, and in the end each spec had it’s strengths and weaknesses.

I felt (and still feel) that RAML is the overall winner- and obviously so otherwise I would be using a different spec 😉 But as I said in closing, because each spec has it’s strengths and weaknesses, it’s important to choose the one that’s right for you.

@mike, thank you this was a helpful comparison. I’d be interested in how you’d score each approach in each category in relative strength terms (ex: Language support: RAML:4 stars, Swagger: 5 stars, Blueprint: 1 star).
@anthony, thank you for the additional details on swagger 2.

Jim, that’s a great idea. I need to update this blog post sooner than later with the new changes in Swagger, as well as updates in the other communities and will definitely try to incorporate a star rating system as well!

That’s correct, however at the time of the comparison (as noted) it was performed against Swagger 1 and RAML 0.8. Also it’s important to note that with Swagger, while the YAML format vastly improves readability of the specification, you still have a maintenance issue as to encompass the wide variety of tooling that Swagger offers you need to have an up-to-date Swagger JSON specification, and an up-to-date Swagger YAML specification.

For an updated comparison of Swagger 2 vs RAML 1, I would suggest viewing the API Specification Comparison Tool, as suggested at the very top of this article noting that specifications have indeed evolved since July 2014 😉

I found huge limitations in Swagger regarding full support of json schemas. I wasn’t able to declare patternProperties and arrays with multiple types. I had to switch to RAML which supports both use cases with remarkable simplicity.
During my transition, I noticed a spare of at least 25% of number of YAML lines in RAML versus Swagger without losing readability, so RAML still wins in this category.
Regarding the editors, I installed Swagger 2.0 Web Editor and it is a bit buggy, sometimes it doesn’t refresh the error list correctly. RAML Atom editor is clearly smoother.

I’d like to present the raml-json-api API-code generator – https://github.com/RJAPI/raml-json-api, which is now at 1.6.4 stable release and it becomes pretty simple to create any API with versatile functionality relying on this tool. Will be happy if someone, who want to build great things, would like to contribute with any code/issues/proposals. Cheers.