Dans le monde de la description d’API, on entend souvent parler de Swagger, d’OpenAPI ou d’OpenAPI Spec. Mais qui est qui ? Et surtout, que choisir ?

Je ne vais pas le cacher, je suis un grand fan de RAML, une alternative à Swagger. Ce langage de modélisation offre plus de possibilités pour réutiliser des concepts dans la définition et la documentation de nos APIs. Et surtout, il a été le premier à proposer une approche Contract-First ! Pourtant, il faut avouer que Swagger est bien plus populaire et bien plus répandu que RAML. Ce n’est pas toujours la meilleure technologie qui gagne 1 !

De Swagger à l’OpenAPI

Swagger est la solution la plus populaire dès le début. Notamment grâce à son approche Code-First et ses annotations Java pour générer la documentation. Fin 2015, alors que RAML gagne en popularité, SmartBear donne la spécification Swagger en version 2.0 à la Linux Foundation pour créer l’OpenAPI Initiative 2 et en profite pour s’entourer d’acteurs majeurs. Dès début 2016, les spécifications de Swagger sont renommées en l’OpenAPI Specification.

MuleSoft rejoindra plus tard l’OAI et se positionnera sur un axe de conception (par opposition à la description/contrat d’interface). Ils proposent l’API Modeling Framework dont l’objectif est d’être le pont être le monde RAML et OpenAPI.

Swagger ou OpenAPI Spec ?

SmartBear continue d’éditer des outils sous le nom de Swagger autour de l’OpenAPI Specification. Cette spécification se cache souvent sous le terme d’OAS. Et la documentation officielle fait souvent référence à l’OpenAPI (fka Swagger) 3.

En 2017, l’OpenAPI Initiative annonce l’avant-première de l’OpenAPI 3 avec sa spécification de l’OpenAPI Spec 3.0.

Ce qu’il faut retenir

Vous êtes perdu ? Moi aussi parfois ! Comme le rappelle SmartBeart, OAS se veut être une spécification libre de tout éditeur alors que Swagger est l’implémentation bien connue. Nous pouvons donc résumer ainsi :

  • l’OpenAPI Spec est la spécification
  • OpenAPI 3.0 est la version 3 de la spécification
  • Swagger est une suite d’outils implémentant la spécification

Vous avez compris ? Il faut suivre l’OpenAPI Spec et utiliser des outils qui implémentent la dernière version, à savoir l’OpenAPI 3.0 ! 😀

  1. Je me rends compte que cette note fait suite à celle-ci.
  2. Connu également sous l’acronyme OAI.
  3. OpenAPI formerly known as Swagger.