Swagger avec Spring Boot
UP ASI
Bureau E204
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 1
PLAN DU COURS
– Introduction
– Swagger
– Intégration Swagger
– Configuration Swagger
– Configuration avancée Swagger
– Personnalisation documentation Swagger
– Place à la pratique
– TP
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 2
Introduction
• La documentation d’un logiciel aide à expliquer
comment utiliser un service ou un programme.
• Elle faciliter la maintenance ainsi que le développement
ultérieur d’un système.
• C’est une étape très importante dans le cas d’une API
(Une API permet de faire communiquer deux
programmes ensemble et d’échanger des données).
• Elle contient les informations nécessaires sur les APIs.
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 3
Swagger
• Swagger est une spécification permettant de simplifier la
tâche de documentation des APIs REST.
• Swagger analyse le code et expose la documentation
sur une URL afin d’être utilisé par les
développeurs/opérationnels.
• Les API sont toujours synchronisées puisque la
documentation des méthodes, des paramètres et des
modèles est intégrée au code du serveur.
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 4
Swagger
• Swagger affiche la liste de tous les endpoints de l’API
avec des informations détaillées, les paramètres et le
schéma de sortie au format JSON.
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 5
Swagger
• Swagger-UI fournit une interface stylisée pour tester les
endpoints.
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 6
Intégration Swagger
• Pour intégrer Swagger dans une application web, il suffit
juste d’ajouter cette dépendance dans le fichier
[Link] et puis faire maven update de votre projet:
<dependency>
<groupId>[Link]</groupId>
<artifactId> springfox-boot-starter </artifactId>
<version> 3.0.0 </version>
</dependency>
• Le projet Springfox automatise la documentation des
API construites avec Spring.
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 7
Intégration Swagger
• Pour activer la prise en charge de la
spécification Swagger, il faut placer l'annotation
@EnableSwagger2 dans la classe main (contenant la
méthode main et permettant de scanner les packages
de l’application).
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 8
Configuration Swagger
• Créez une classe SwaggerConfig dans un nouveau
package appelé configuration.
@Configuration
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis([Link]())
.paths([Link]())
.build();
}
}
• La classe Docket gère toutes les configurations.
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 9
Configuration Swagger
La classe Docket contient les éléments suivants :
• Select: Initialiser une classe de ApiSelectorBuilder pour
donner l’accès aux méthodes de personnalisation.
• paths : filtrer selon l'URI des requêtes.
• apis : filtrer la documentation à exposer selon les
contrôleurs.
- basePackage: trier selon le Package.
- any: documenter toutes les classes dans tous les
packages.
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 10
Configuration Swagger
• Redémarrez votre application
• Swagger est capable de générer une documentation
détaillée au format JSON.
[Link]
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 11
Configuration Swagger
• Swagger est capable d’accéder à une version au
format HTML via l'adresse suivante:
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 12
Configuration Swagger
• Informations personnalisées
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis([Link]())
.paths([Link]())
.build().apiInfo(apiInfo());
}
private ApiInfo apiInfo () {
return new ApiInfoBuilder()
.title("Swagger Configuration for tpStockProject")
.description("\"Spring Boot Swagger configuration\"")
.version("1.1.0").build();
}
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 13
Configuration avancée Swagger
Filtrage des APIs
• La documentation contient le contrôleur d'erreur
de Spring, pour l'éliminer il faut utiliser les filtres.
• La méthode basePackage permet de demander à
Swagger de ne rien documenter en dehors du package
spécifié.
.apis([Link]("[Link]
.spring"))
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 14
Configuration avancée Swagger
Filtrage des APIs
• La méthode paths permet d’éliminer une méthode
de documentation.
.paths([Link]("/client.*"))
• [Link]("/client.*") permet de passer
une expression régulière qui n'accepte que les URI
commençant par /client.
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 15
Personnalisation documentation Swagger
Personnaliser la documentation grâce aux annotations
• Pour personnaliser les informations, il faut appliquer des
annotations sur les classes des contrôleurs ainsi que leurs
méthodes.
• @Api : permet d’ajouter une description pour chaque API.
@Api(tags = "Client management")
• @ApiOperation : permet de définir une description pour
chaque opération/méthode.
@ApiOperation(value = "Récupérer la liste des clients")
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 16
Personnalisation documentation Swagger
Personnaliser la documentation grâce aux annotations
Les informations définies
dans ces annotations se
retrouvent dans la page
[Link]
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 17
Place à la pratique
Une annotation de la couche Controller fournie par
Spring va être reflétée dans Swagger.
public Client retrieveClient(@PathVariable("client-id") Long clientId) {
@PathVariable sera reflété comme suit:
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 18
Place à la pratique
Ajouter un client
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 19
Place à la pratique
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 20
TP
Exposer les services implémentés avec Swagger pour les
tester.
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 21
Swagger avec spring boot
Si vous avez des questions, n’hésitez pas à nous
contacter :
Département Informatique
UP ASI
Bureau E204
© 2021-2022 – ESPRIT – Module Architecture des SI II (Spring) 22
