Annotations Swagger

1. @Api : Annotation de classe @Api(value="Contrôleur test", tags="Fonctionnalités de test")
2. @ApiOperation : Annotation de méthode @ApiOperation(value="Méthode test", tags="Opérations de test")
3. @ApiImplicitParam : Description de paramètre individuel @ApiImplicitParam(name = "dateFin", value = "Paramètre date", dataType = "String")
4. @ApiImplicitParams : Groupe de paramètres @ApiImplicitParams({@ApiImplicitParam(...), @ApiImplicitParam(...)})
5. @ApiModel : Description d'entité @ApiModel(value="Modèle test")
6. @ApiModelProperty : Documentatino de propriété @ApiModelProperty(value="Champ test")

Configuration de Swagger

1. Dépenadnces Maven

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. Classe de configuration

@Configuration
@EnableSwagger2
public class DocumentationConfig {

    @Bean
    public Docket generateApiDocumentation() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(informationsApi())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.api.controller"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo informationsApi() {
        return new ApiInfoBuilder()
            .title("API REST de Gestion")
            .description("Documentation complète des services")
            .version("1.0")
            .build();
    }
}

3. Contrôleur annoté

@Api(value = "Gestion des tests")
@RestController
@RequestMapping("/api/test")
public class TestController {

    @ApiOperation(value = "Méthode de test")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "idProjet", value = "Identifiant projet", dataType = "String"),
        @ApiImplicitParam(name = "dateDebut", value = "Date de début", dataType = "String")
    })
    @GetMapping("/execute")
    public ResponseEntity<Resultat> executerTest(
        @RequestParam String idProjet, String dateDebut) {
        return ResponseEntity.ok(new Resultat("OK"));
    }
}

Sécurisation de l'interface Swagger

1. Ajout de dépendance

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.3</version>
</dependency>

2. Configuration dans application.yml

swagger:
  basic:
    enable: true
    username: admin
    password: secure123

3. Activation de l'UI sécurisée

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class DocumentationConfig {
    // Configuration existante inchangée
}

Ajout de paramètres globaux

@Bean
public Docket generateApiDocumentation() {
    return new Docket(DocumentationType.SWAGGER_2)
        .globalOperationParameters(configurerEnTetes())
        // ... autres configurations
}

private List<Parameter> configurerEnTetes() {
    ParameterBuilder tokenBuilder = new ParameterBuilder();
    List<Parameter> parametres = new ArrayList<>();
    tokenBuilder.name("Authorization")
                .description("Jeton d'authentification")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
    parametres.add(tokenBuilder.build());
    return parametres;
}

Accès à l'interface

Interface Swagger disponible à l'adresse : http://localhost:8080/swagger-ui.html