Contrairement à la SOA, des contrats de type WSDL (Web Services Description Language) sont rarement utilisés dans une architecture Microservices. C'est pour cela qu'il est primordial d'avoir une documentation standardisée et de très bonne qualité.
Afin de bénéficier de Swagger, nous allons importer cette dépendance dans notre pom.xml :
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>Pour générer la documentation, il faut placer l'annotation @EnableSwagger2 dans la classe contenant avec la méthode Main. Dans notre cas, il s'agit de MicrocommerceApplication.
package com.ecommerce.micrommerce;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class MicrommerceApplication {
public static void main(String[] args) {
SpringApplication.run(MicrommerceApplication.class, args);
}
}Il faut aussi ajouter cette ligne dans application properties :
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
… qui permettra de donner toutes les informations nécessaires à Swagger.
Redémarrez votre application et rendez-vous sur http://localhost:9090/v2/api-docs. Vous obtenez alors la documentation complète de votre microservice, générée au format JSON.
Vous pouvez également accéder à une version au format HTML à l'adresse suivante : http://localhost:9090/swagger-ui/, comme illustré ci-après :
Dans cette version HTML de la documentation générée par Swagger, nous retrouvons toutes les méthodes que nous avons définies. En cliquant sur une méthode, nous retrouvons les détails sur :
le type de données qu'elle accepte en entrée et qu'elle produit en retour ;
un exemple d'une réponse typique ;
tous les codes d'erreur qu'elle peut générer.
Configurez Swagger
Ce niveau de documentation peut sembler suffisant, mais dans une application professionnelle, il peut être utile de la personnaliser de multiples manières. Nous allons donc voir comment créer une classe de configuration pour Swagger.
Créez une classe SwaggerConfig dans un nouveau package appelé "configuration", et écrivez le code suivant :
SwaggerConfig.java
package com.ecommerce.micrommerce.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}Explications
L'annotation @Configuration appliquée à la classe permet de remplacer un fichier de configuration classique en XML. Elle nous donne accès à plusieurs méthodes très intéressantes pour la personnalisation de Swagger, grâce à la classe Docket qui gère toutes les configurations.
On commence alors par initialiser un objet Docket en précisant que nous souhaitons utiliser Swagger 2.
select permet d'initialiser une classe du nom de ApiSelectorBuilder qui donne accès aux méthodes de personnalisation suivantes. Ne vous attardez pas sur cette méthode, elle n'est d'aucune utilité pour la suite.
apis est la première méthode importante. Elle permet de filtrer la documentation à exposer selon les contrôleurs. Ainsi, vous pouvez cacher la documentation d'une partie privée ou interne de votre API. Dans ce cas, nous avons utilisé RequestHandlerSelectors.any().
RequestHandlerSelectors est un prédicat (introduit depuis Java 8) qui permet de retourner TRUE ou FALSE selon la condition utilisée. Dans ce cas, nous avons utilisé any qui retournera toujours TRUE. En d'autres termes, nous indiquons vouloir documenter toutes les classes dans tous les packages. RequestHandlerSelectors offre plusieurs autres méthodes, comme annotationPresent qui vous permet de définir une annotation en paramètre. Swagger ne documente alors que les classes qu'il utilise. La plus utilisée est basePackage qui permet de trier selon le Package. Nous allons voir un exemple juste après.
paths : cette méthode donne accès à une autre façon de filtrer : selon l'URI des requêtes. Ainsi, vous pouvez, par exemple, demander à Swagger de ne documenter que les méthodes qui répondent à des requêtes commençant par "/public" .
Appliquons tout cela à notre API pour mieux comprendre.
Vous avez certainement remarqué que la documentation contient le contrôleur d'erreur de Spring, comme illustré ci-après :
Ce contrôleur n'a rien à faire dans notre documentation, nous allons donc utiliser les filtres pour l'éliminer :
package com.ecommerce.micrommerce.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig
{
@Bean
public Docket api()
{
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.ecommerce.micrommerce.web"))
.paths(PathSelectors.any())
.build();
}
}Nous utilisons la méthode basePackage du prédicat RequestHandlerSelectors afin de demander à Swagger de ne rien documenter en dehors du package "web" qui contient notre code. Si vous redémarrez votre application, vous verrez que basic-error-controller a disparu.
Nous avons créé, dans le chapitre sur Spring Data JPA, une méthode de test qui répond à l'URL /test/produits/{prix}.
Éliminons-la de la documentation grâce à la méthode paths :
@Configuration
@EnableSwagger2
public class SwaggerConfig
{
@Bean
public Docket api()
{
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.ecommerce.microcommerce.web"))
.paths(PathSelectors.regex("/Produits.*"))
.build();
}
}PathSelectors.regex("/Produits.*") permet de passer une expression régulière qui n'accepte que les URI commençant par /Produits.
Actualisez : la méthode de test a disparu.
Personnalisez la documentation grâce aux annotations
La dépendance Swagger que nous avons utilisée nous donne accès à un certain nombre d'annotations pour personnaliser la documentation directement dans nos classes.
Nous pouvons ainsi ajouter une description pour chaque API grâce à l'annotation @Api , comme illustré ci-après :
@Api("API pour les opérations CRUD sur les produits.")
@RestController
public class ProductController
{
...
}Nous pouvons également définir une description pour chaque opération/méthode à l'aide de l'annotation @ApiOperation :
//Récupérer un produit par son Id
@ApiOperation(value = "Récupère un produit grâce à son ID à condition que celui-ci soit en stock!")
@GetMapping(value = "/Produits/{id}")
public Product afficherUnProduit(@PathVariable int id)
{
...
}En résumé
Nous pouvons maintenant documenter notre API grâce à Swagger.
Ça y est, vous avez tous les éléments pour créer vos microservices ! Dans le prochain chapitre, vous allez compléter notre application !
