Intégration de Swagger (OpenAPI) dans Spring Boot

Version récente et configuration plus simple.

Introduction

Swagger UI (aujourd’hui appelé OpenAPI) permet de générer automatiquement une documentation interactive avec une API REST Spring Boot ou autre.

Documentation officielle

Elle permet :

• Explorer tous les endpoints (GET, POST, PUT, DELETE)
• Tester les requêtes directement depuis le navigateur
• Exposer la documentation API sous forme JSON OpenAPI

Dépendances

Maven (pom.xml) :

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.7.0</version> <!-- ou dernière version -->
</dependency>

Gradle :

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'

Liens vers les versions disponibles sur le repo mvn

En théorie, aucune configuration supplémentaire n’est requise, il suffit de lancer l’application.

URL de votre application (si port 80)	Description
http://localhost:8080/swagger-ui.html	Interface Swagger UI
http://localhost:8080/v3/api-docs	Fichier JSON OpenAPI généré automatiquement

Personnalisation de la documentation

Dans notre étude de cas Waouf Waouf, on peut apporter des informations supplémentaires. Ces informations apparaissent en haut de la documentation Swagger UI.

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.Contact;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "API Fédération Canine (Waouf Waouf)",
        version = "1.0",
        description = "Documentation de l’API publique pour la gestion des chiens et des concours",
        contact = @Contact(name = "Phil", email = "contact@monwaoufwaouf.fr")
    )
)
public class OpenApiConfig {
}

Exemple d’annotation pour notre contrôleur

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/chiens")
@Tag(name = "Chiens", description = "Endpoints liés aux chiens et à leurs propriétaires")
public class ChienController {

    private final ChienService service;

    public ChienController(ChienService service) {
        this.service = service;
    }

    @GetMapping
    @Operation(
        summary = "Liste tous les chiens",
        description = "Retourne la liste complète des chiens enregistrés dans la base de données"
    )
    public List<ChienDto> getAll() {
        return service.getAllChiens();
    }

    @PostMapping
    @Operation(
        summary = "Ajoute un nouveau chien",
        description = "Crée un nouvel enregistrement de chien dans la base"
    )
    public ChienDto create(@RequestBody ChienDto dto) {
        return service.create(dto);
    }
}

Les annotations Swagger enrichissent automatiquement la documentation générée :

• @Tag : Regroupe les endpoints par catégorie
• @Operation : Décrit chaque méthode (titre, description)

Configuration de Swagger dans application.yml

Swagger restera actif en dev et sera désactivé en prod !

springdoc:
  api-docs:
    path: /api-docs
    enabled: true
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method
    tagsSorter: alpha
    displayRequestDuration: true

Désactiver Swagger en production

# application.yml
springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

---
spring:
  config:
    activate:
      on-profile: prod
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

options supplémentaires

Propriété	Description
springdoc.api-docs.path	Change le chemin du JSON OpenAPI (par défaut /v3/api-docs)
springdoc.swagger-ui.path	Définit le chemin de l’interface Swagger
springdoc.swagger-ui.filter	Ajoute une barre de recherche dans l’interface
springdoc.show-actuator	Intègre les endpoints /actuator dans Swagger
springdoc.packages-to-scan	Limite les packages analysés
springdoc.paths-to-match	Filtre les endpoints exposés dans la doc

Exemple de code avec l’Adhérent

import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@RestController
@RequestMapping("/api/adherents")
@Tag(name = "Adhérents", description = "Gestion des adhérents de la Fédération Canine")
public class AdherentController {

    @GetMapping("/{id}")
    @Operation(summary = "Récupère un adhérent par son ID")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "Adhérent trouvé"),
        @ApiResponse(responseCode = "404", description = "Aucun adhérent trouvé")
    })
    public AdherentDto getAdherent(@PathVariable Long id) {
        // ...
        return new AdherentDto();
    }
}

Liens des documentations officielles

Ressource	Lien
Springdoc OpenAPI (officiel)	https://springdoc.org
Spécification OpenAPI 3.0	https://swagger.io/specification/
Exemples Springdoc GitHub	https://github.com/springdoc/springdoc-openapi
Annotation @OpenAPIDefinition	https://javadoc.io/doc/io.swagger.core.v3/swagger-annotations/latest/index.html