What is distinctive purpose of API Blueprint vs Swagger?

rest swagger apiblueprint
Pramod S. Nikam picture Pramod S. Nikam · Sep 17, 2017 · Viewed 7.9k times · Source

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

miiila picture miiila · Sep 17, 2017

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.

Related questions

Good rest code generation and documentation tool

I have been considering a documentation tool for building a backend for a web service to be used in multiple clients along with OAuth and possibility of multiple revisions. I already knew about apiary but doing a little research I …

Read More
How to describe a model in Swagger for an array with simple objects?

I have a REST services to document, some of them accepts simple array like: [ { "name":"a" }, { "name":"b" }, { "name":"c" } ] How do I describe this in Swagger model section ? I can only create 'named array' like model { properties: { "arr": { "type":"…

Read More
How to generate java client code for swagger REST API documentation

My scenario is the following. I have a swagger .json eg.: http://petstore.swagger.io/v2/swagger.json I want to use a generated java client for the REST API above, like: PetApi petApi = new PetApi(); Pet pet = new Pet; …

Read More