Documenter les APIs avec Swagger (3/4) — Mise en scène de l’ensemble

Dans cette série d’articles, je vais introduire les différents outils de Swagger. Swagger est un outil très pratique de documentation des APIs. Il permet de générer de la documentation “vivante”, permettant ainsi que la documentation soit toujours à jour, ce qui est très difficile à réaliser sans ce genre d’outil. Il permet également de générer du code automatiquement, permettant au développeur de se concentrer sur le coeur de son activité. Enfin, il repose sur un format de spécifications open source.

Cet article est donc décomposé en quatre parties :

• Introduction,
• Le framework Swagger,
• La mise en scène de l’ensemble,
• Le test de l’API.

Il y a deux manières d’utiliser la documentation :

• soit par Swagger UI embarqué dans le serveur,
• soit par Swagger UI tournant en autonome.

Utilisation de Swagger UI embarqué dans le serveur

Mise en place de l’environnement

docker run \
    --rm \
    -v ${PWD}:/local \
    swaggerapi/swagger-codegen-cli \
    generate -i /local/swagger.yaml -l nodejs-server -o /local/out

Le résultat de la commande est :

[main] INFO io.swagger.parser.Swagger20Parser - reading from /local/swagger.yaml
[main] INFO…