Swagger vs RAML vs API Blueprint

Camilo Castro
Jul 22, 2016 · 2 min read
Desktop by Jeff Sheldon

This is a personal opinion about these tools. When I’m creating an API I use the design first approach. That means that first you have to document the API and only after that begin coding. Many projects that I worked on didn’t have proper documentation or the API design was a second class citizen. Those projects were really frustrating experiences since the API definitions and responses changed in the middle of the project and I have to rework already shipped parts of the software.

Swagger

I don’t like swagger because it’s a developer only API documentation tool. That means that only the people who can code can document the project API. It’s easier to teach someone how to document an API than teach them how to code and use Swagger for automatic documentation generation. Also the API structure and implementation will be tied to the language and framework used by the software. How do you document an API with micro-services that use different tools and frameworks?. It would be a mess. I personally prefer to detach the documentation and implementation.

RAML

The main problem with RAML is that the latest version (1.0) does not have proper tools. If you use the 0.8 version you will find more tools, but lose all the new features the latest version brings. Other problem is the YAML syntax. I was frustrated because following the tutorial showed errors relating spaces in the API workbench tool. In my opinion using RAML its more error prone than using simple Markdown.

API Blueprint

This method is my favourite. It uses simple to understand Markdown like syntax for documentation and mson for schemas. Also there are many tools for generating html files and mock servers. Finally you can also use a cloud service like https://apiary.io for hosting and creating your API documents.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store