you are here

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):

RAML: 66 watching, 639 starred, and 49 forks
Swagger: 208 watching, 2,113 starred, and 614 forks
API Blueprint: 77 watching, 898 starred, and 399 forks

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:

RAML: MuleSoft, SOA, AngularJS, Intuit, Box, PayPal, & Programmable Web
Swagger: Reverb, 3Scale, & Apigee
API Blueprint: Apiary

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:

RAML: Simple, easy to use low-key website
Swagger: Feels incomplete. Landing page with links to Github/ wiki
API Blueprint: Simple, easy to use, more artistic site

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:

RAML: Simple, human readable format
Swagger: JSON
API Blueprint: Similar to JSON

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.

Winner: RAML

Editing Tool:

RAML: API Designer + Console
Swagger: Swagger Editor + Console
API Blueprint: Couldn’t find one

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:

RAML: Very easy, everything in Github repos
Swagger: Everything in Github repos
API Blueprint: Installation required

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:

RAML: MuleStudio APIKit (Visual, drag and drop), Osprey (Node)
Swagger: Tools for most popular languages
API Blueprint: Node & .Net bindings

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:

RAML: Single or multiple page documentation builder (PHP only)
Swagger: Single page documentation builder
API Blueprint: Single or multiple page 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:

RAML: JS, Java, Node, PHP, Python, Ruby
Swagger: Clojure, Go, JS, Java, .Net, Node, PHP, Python, Ruby, Scala
API Blueprint: Node, .Net

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.

Share this Page:
Facebook Twitter Linkedin Reddit Tumblr Email

Leave a Reply

Your email address will not be published. Required fields are marked *