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