• 20 heures
  • Difficile

Ce cours est visible gratuitement en ligne.

course.header.alt.is_video

course.header.alt.is_certifying

J'ai tout compris !

Mis à jour le 17/08/2018

Documentez votre microservice avec Swagger 2

Connectez-vous ou inscrivez-vous gratuitement pour bénéficier de toutes les fonctionnalités de ce cours !

Contrairement à la SOA, des contrats de type WSDL 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é

À partir de votre code, Swagger est capable de générer une documentation détaillée au format JSON, répondant aux spécificationsOpenAPI. Il vous offre également la possibilité de visualiser cette documentation dans un format HTML élégant.

Afin de bénéficier de Swagger, nous allons importer 2 dépendances dans notre pom.xml :

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.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.microcommerce;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class MicrocommerceApplication {

    public static void main(String[] args) {
        SpringApplication.run(MicrocommerceApplication.class, args);
    }
}

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.html, comme illustré ci-après :

Figure 17
Documentation Swagger au format HTML

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.

Configurer Swagger

Ce niveau de documentation peut sembler suffisante, 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.microcommerce.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. Nous 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 conditions 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 documentera 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 :

Figure 18
Contrôleur affiché inutilement dans notre documentation

 Ce contrôleur n'a rien à faire dans notre documentation, nous allons donc utiliser les filtres pour l'éliminer :

....

@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.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}. 

Méthode de test à ne pas documenter
Méthode de test à ne pas documenter

É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( description="API pour es 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) {
            ......
        }

Vous trouverez ici dans la documentation toutes les annotations possibles.

Ça y est, vous avez tous les éléments pour créer vos Microservices ! à vous de valider vos connaissances en complétant notre application dans l'activité qui suit !

Exemple de certificat de réussite
Exemple de certificat de réussite