Aujourd’hui, nous n’allons pas parler de RAML mais plutôt de Swagger. Ce framework se compose d’une spécification ainsi qu’un ensemble d’implémentations pour décrire, produire, consommer et visualiser des APIs RESTful. Même si l’adoption de RAML progresse, Swagger reste la solution la plus connue et répandue pour documenter vos APIs RESTful. Ce ne sont d’ailleurs pas les seuls solutions car il existe bien d’autres DSL d’APIs RESTful.

Alors que RAML permet d’avoir une approche Top-Down (Contract-First), Swagger est initialement orienté Bottom-Up (Code First). Il existe quelques comparatifs (un qui commence à dater et un plus récent) entre les 3 leaders : Swagger, RAML et API Blueprint.

La Linux Foundation a annoncé la création de l’Open API Initiative dont l’objectif est d’élaborer des spécifications standards qui fourniront des métadonnées RESTful pour les APIs. Cette initiative est supportée dans des géants du web et des acteurs majeurs de la gestion d’APIs. Par la même occasion, Swagger intègre l’OAI et devient l’Open API Definition Format (OADF) (plus d’information).

Après la publication de RAML 1.0 et maintenant une initiative pour créer un standard autour de Swagger, il est de plus en plus évident que la documentation des APIs RESTful est un enjeu important et que la compétition ne fait que commencer !