Introduction
Comment documenter une API ?
Nous disposons de certains outils qui peuvent générer automatiquement les documentations d’API pour nous.
Nous allons voir comment nous pouvons documenter une API développée avec Spring Boot et Swagger2.
Swagger2 est un outil fantastique pour documenter une API REST. Les propriétés de l’API peuvent être décrites dans des métadonnées JSON ou YAML dans Swagger2.
L’interface utilisateur Swagger est agréable, idéale pour visualiser et renseigner notre API.
Elle génère une documentation HTML à l’aide des métadonnées Swagger2.
En outre, nous pouvons également utiliser cette API comme Postman pour tester notre API.
SpringFox
SpringFox est un projet qui fournit une documentation JSON automatisée pour les APIs construites avec Spring. Si nous voulons mettre à jour la documentation chaque fois que le code est modifié, SpringFox le fera pour nous. Il peut inspecter automatiquement les classes, détecter les controlleurs, les méthodes, les classes de modèles qu’ils utilisent, et les URLs vers lesquelles ils sont mappés.
Ajouter les dépendances dans Maven et le pom.xml
La dernière version à la publication de cet article est la version 3.0.0
Ajoutez ce code dans le pom.xml :
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>Ajouter les dépendances avec Gradle
implementation 'io.springfox:springfox-swagger-ui:3.0.0'Configuration basique de Swagger2
@Configuration
@EnableSwagger2
public class SwaggerConfig{
@Bean
public Docket myUnicornAPI() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.build();
}L’annotation @EnableSwagger2 indique que le support Swagger sera activé. Cette annotation est fournie par SpringFox. Pour la configuration de Swagger, nous devons créer une instance de “Docket Bean”.
Le “docket bean” est utilisé pour configurer le comportement de la documentation. Swagger examinera cette instance et déterminera comment il doit documenter votre application Spring.
Ici, nous initialisons l’instance du bean qui est configurée pour la documentation Swagger2 avec cette ligne new Docket(DocumentationType.SWAGGER_2).
La méthode select() est utilisée pour appeler la classe ApiSelectorBuilder, qui fournit les méthodes permettant de personnaliser le comportement de Swagger. Après toute la configuration, nous appellerons la méthode build() pour obtenir l’instance du docket bean.
La documentation de notre API est maintenant configurée de base, un moyen simple de vérifier si Swagger est bien activé, démarrez votre application Spring Boot, et accédez à cette adresse :
http://localhost:8080/v2/api-docs
Le port par défaut d’une application Spring Boot est 8080, mais vous pouvez facilement modifier ce port dans le fichier de configuration application.properties
Voilà sur quoi vous devriez tomber, la documentation en JSON, mais pas de panique :
Swagger est fonctionnel, et l’API est documentée. Vous pouvez consulter la documentation HTML dans l’éditeur Swagger en ligne.
Rassurez vous, il existe un moyen facile pour éviter de passer par cet éditeur en ligne et générer automatiquement une jolie documentation, et tout ça, avec Swagger UI.
Swagger UI
L’interface graphique de la documentation HTML peut être réalisée en utilisant donc Swagger UI.
Ajout de la dépendance avec Maven :
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>Ajout de la dépendance avec Gradle :
implementation 'io.springfox:springfox-swagger-ui:3.0.0'Toujours vérifier les dernières versions disponibles.
Après l’ajout de la dépendance Maven ou Gradle, redémarrez votre application Spring Boot et naviguez vers cette URL et admirez :
http://localhost:8081/swagger-ui/index.html
Personnalisation de la documentation Swagger2
Imaginons un controller “book-controller”, un controller “user-controller”, et un autre controller “basic-error-controller” ? Que faire si nous voulons que le controller “basic-error” n’apparaisse pas dans la documentation ?
Pour cela, nous devons utiliser les méthodes paths() et apis() de la classe ApiSelectorBuilder.
La méthode paths() d’ApiSelectorBuilder est utilisée pour configurer les chemins des APIs, qui devraient être couverts par la documentation Swagger.
Les chemins peuvent être définis par des pathSelectors. Les pathSelectors fournissent un filtrage supplémentaire avec des prédicats qui analysent les chemins de requête de votre application et les définissent en fonction de vos besoins.
Plusieurs méthodes sont disponibles : any(), none(), regex() ou ant().
Lorsque nous codons les controllers, nous avons utilisé l’annotation @RestController.
Nous pouvons filtrer les controllers avec cette annotation.
Pour cela, nous pouvons utiliser RequesthandlerSelector en paramètre de la méthode apis() de la classe apiSelectBuilder puisque apis() permet de sélectionner les gestionnaires de requêtes.
En exemple, dans la classe SwaggerConfig :
@Bean
public Docket myUnicornAPI() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.paths(PathSelectors.any())
.build();
}Donc maintenant, nous avons notre “user-controller” et notre “book-controller”, le controller “basic-error” a disparu, pratique si l’on ne veut pas afficher la documentation de tous nos controllers.
Nous pouvons également définir une nouvelle méthode dans la classe SwaggerConfig, qui permet nous permettra d’ajouter des informations telles qu’un titre, une description, version :
@Bean
public Docket myUnicornAPI() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Library API")
.description("This is the mock Library API can be used to practise the swagger documentation")
.version("1.0.0")
.build();
}Ce qui donne dans l’interface après un redémarrage de l’application :
Voilà pour la première partie de Swagger & Swagger UI, c’est très simple à mettre en place et cet outil permet de générer automatiquement les documentations de nos API, et tout ça dans une interface graphique agréable.
