Swagger vs RAML vs API Blueprint
--
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.
