MIKESTOWE.COM

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

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

  • Chris says:

    The analysis does not factor in the broader swagger community and work on swagger 2.0.

    • mike says:

      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.

  • Swagger 2.0 is here now. At the apigee “I love APIs 2014” conference right now so got to watch Tony Tam discuss new features in 2.0.

    http://www.marketwatch.com/story/reverb-announces-swagger-20-a-next-generation-interface-to-connect-apis-and-cloud-services-2014-09-08

    Here’s my notes from his talk for what it’s worth…

    Swagger 2.0 and model-driven APIs

    * created by Reverb
    * describe your API
    * interactive docs
    * swagger much bigger than just swagger UI
    * complete API framework
    *
    * description format (swagger document)
    * reflection and discovery (annotate it)
    * documentation
    * SDK generation
    * server-side codegen (partial or full dataset for interacting with API)
    * server metrics
    * SOAP UI (automated test tool), points at swagger doc
    * SnapLogic (Swagger snap), automatic connection with swagger-based APIs
    * de-facto description format in RESTful API world
    *
    * 10,000 production instances
    * 2000+ downloads / day of Java version
    * 500+ people in working group
    * 10000+ developers using
    * thousands devs contributing to OSS
    * 2.0
    *
    * evolve the JSON syntax
    * a human friendly authoring format
    * vendor extensions
    * tooling refresh
    * validation tools
    * Swagger Editor (AngularJS, YAML)
    * WSDL/WADL (XML to define JSON???)
    * RESTful, but not trying to solve every problem, keep it simple, allows tooling
    * .NET (Swashbuckle) larger than Java deployment
    * Swagger is bottoms-up, doesn’t prescribe workflow
    * contractual and describable, but developer shouldn’t have to know biz logic
    * Node.js good backend for leading into Swagger APIs
    * Great for micro services, JOSN pointer in 2.0 master spec that can point to other services
    * Ability to produce a single shippable file in 2.0
    * Swagger 2.0 allows for vendor extensions that fall out of standard specs, yay!
    * Badge project for those who product valid Swagger-based API
    * Migration tools for 1.0 to 2.0, dependency changes
    * Don’t want to become so vendor poisoned it’s doomed (CORBA)
    * Make $ on support to fill a need, not core biz
    * 5 years from now – foster communication, more use cases, better design, more open communication, level playing field

  • Cory says:

    Disclaimer: I work for MuleSoft, a major contributor to RAML. However […]

    Just in case anyone missed it. (I almost did.)

    Thanks for the post and for the disclaimer, but it’s impossible for you to be impartial. Absolutely not saying it’s your intention, more just a statement of fact.

    • mike says:

      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.

  • API Blueprint’s writing spec is certainly not “Similar to JSON”, it’s mostly markdown-like. It does, however, *compile* into JSON.

  • Jim says:

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

  • Marc says:

    I believe that the API Console and Editor for API Blueprint _IS_ Apiary.

    Also, in terms of Writing Spec, RAML _is_ YAML, while API Blueprint is Markdown, which is pretty damn human readable.

  • Todd says:

    Very helpful, thanks!

    Possible misprint under the API Builder category?:

    “Despite having the smallest community, Swagger has tools…”

    You earlier state that Swagger has the largest community by a landslide.

  • Radha says:

    H mike,
    Are you sure that RAML 0.8 does not have.NET language support? I checked few websites where they are talking about .NET support in RAML.
    Eg:http://blogs.mulesoft.com/raml-tools-net-developer/

    Thanks,
    Radha

    • mike says:

      Hi Radha,
      You are correct RAML now has fairly strong .NET support. Please keep in mind this post was created awhile ago, and as such may not have the most up-to-date information.

      I will work on getting it updated, but otherwise be sure to check out the Spec Comparison Chart.

      Thanks!

  • kartu says:

    Swagger (at least version 2) supports both JSON and YAML markup. So RAML is hardly a winner at “Writing Spec

    • admin says:

      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 😉

      Thanks,
      Mike

  • Jaime says:

    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.

  • [email protected] says:

    I would love to see an update to this posting 2 years later. It would be interesting to see how this has changed.

    • mike says:

      Good idea! This has been on my backlog for awhile, but I’ll try to get an update out soon :)

      • Adam Lane says:

        +1 I need to choose one and am totally unsure what to use! This page has been the best comparison I could find but versions have changed. What is the current overall winner?

  • Arthur Kushman says:

    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.

Leave a Reply

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