Swagger

Dans un contexte d’application REST, il est indispensable d’avoir une documentation de nos API claire et évolutive.
Notre première approche a été le bon vieux document Word, mais il s’est avéré que cette solution posait quelques problèmes de maintenabilité, de lisibilité et de mise à disposition de l’information. Nous sommes donc partis à la recherche de solutions alternatives.

 

Le choix

Il existe différentes solutions pour documenter les APIs :

  • Apiary
  • Swagger
  • Raml
  • …​

Notre choix s’est tourné vers Swagger, celui-ci permettait d’avoir :

  • Un éditeur de documentation ou une documentation directement intégrée dans le code sous la forme d’annotation.
  • Une interface graphique permettant de consulter la documentation mais également de tester nos APIs.

 

L’implémentation

Etant issu du monde JAVA ~ SCALA, je vous propose des exemples d’annotations en SCALA. Mais Swagger est multi langages .NET, JS, GO, Python, …​.

 

Model

@ApiModel("User")

case class User(

      @(ApiModelProperty@field)(position = 1, value = "id", required = true) val id: Long,

      @(ApiModelProperty@field)(position = 2, value = "name", required = true) val name: String,

      @(ApiModelProperty@field)(position = 3, value = "mail", required = false) val mail: Option[String]) {}

 

Ressource

@Api(value = "/user", description = "Operations about user.", produces = "application/json", position = 1)

trait UserHttpService extends HttpService {

  val routes = getUser

  import Json4sSupport._

  @ApiOperation(httpMethod = "GET", response = classOf[User], value = ``)

  @ApiImplicitParams(Array(

    new ApiImplicitParam(name = "idUser", value = "The ID of User", required = true, dataType = "long", paramType = "path")))

  @ApiResponses(Array(

    new ApiResponse(code = 400, message = "ID must long"),

    new ApiResponse(code = 404, message = "User does not exist")

   ))

  def getUser: Route = {

    path("user" / LongNumber){

      id => get(complete(User(id, "name", None)))

    }

  }

}

 

Documentation obtenue

En synthèse

Swagger permet de réaliser simplement la cartographie de vos API REST en décrivant les modèles, les urls, les verbes http, les arguments ainsi que les codes d’erreurs renvoyés. Swagger permet également de tester les API et de générer le code stub client permettant de les consommer.

 

Quelques liens

  • Site officiel http://swagger.io/
  • Github Swagger
  • Auto-promo  l’image docker run -d --name swagger-ui -p 8888:8888 -e "API_URL=YOUR_URL" sjeandeaux/docker-swagger-ui  qui permet une mise en œuvre rapide de Swagger.

Stéphane J.

Commentaires

Yves-E
Cool. Pub : quand on utilise StrongLoop (pour ceux qui font du node.js) on a automatiquement swagger !

Ajouter un commentaire

Tags: