Documenter les APIs avec Swagger (2/4) — Le framework Swagger

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.

Le framework Swagger (https://github.com/swagger-api) comprend plusieurs sous-projets répondant à un objectif bien précis. Voici ceux que l’on va aborder ici :

• Swagger Editor,
• Swagger UI,
• Swagger CodeGen.

Swagger Editor

Swagger Editor (https://github.com/swagger-api/swagger-editor) permet d’éditer les fichiers de spécification au format YAML. Autrement dit, il permet de créer un contrat.

Lancer Swagger Editor :

docker run \
    -d \
    -p 82:8080 \
    swaggerapi/swagger-editor