RAML vs. Swagger vs. API Blueprint
Updated July 7, 2014 @ 16:41 PST
Note – for an updated comparison, check out the API Spec Comparison tool.
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
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)
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.
Overview: Both RAML and Swagger provide intuitive editors with a live console preview allowing you to see exactly what the end product will look like as you are creating and editing your file.
Winner: Tie (RAML & Swagger)
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.
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.
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.
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
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.
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.