What is distinctive purpose of API Blueprint vs Swagger?

Question

I am trying to develop application in cloud native way. I am trying have API first design of my application.

Which API documentation tool should I use? which one is more suitable for API first Contracts? rather which one of it suitable where?

Answer 1

I'd say both formats are suitable for API first approach, so it's a matter of taste (markdown vs yaml/json based) or tool limitation.

You can read a brief summary at https://help.apiary.io/api_101/choosing-format/.

Both formats are open-sourced and have great community and tooling built around them.

• Swagger is YAML (or JSON) format, with focus to be easy to parse and has wide options of extensions and integrations.
• API Blueprint comes with syntax close to Markdown, MSON and full support of all Apiary tooling and open-source tooling.

Both should allow you to describe a broad set of API architectures with design-first approach. Swagger comes with tools to generate a description from code. API Blueprint syntax makes it easier to describe hypermedia/REST APIs.

If you are new to API Description world, we recommend to start with API Blueprint.