Génération Swagger/OpenAPI pour Java : bibliothèques et outils

Génération Swagger/OpenAPI pour Java : aperçu complet des outils et bibliothèques

Le développement moderne d'API REST en Java est impensable sans une documentation de qualité. La norme OpenAPI (anciennement connue sous le nom de Swagger Specification) est devenue la norme industrielle de facto pour décrire les API HTTP. Dans cet article, nous allons détailler les principales bibliothèques et outils pour générer des spécifications OpenAPI dans les applications Java, leurs fonctionnalités, des exemples d'utilisation et des critères de sélection.

Qu'est-ce qu'OpenAPI et pourquoi en a-t-on besoin ?

OpenAPI est une spécification qui décrit une API RESTful au format JSON ou YAML. Elle comprend :

\n
• la liste des points de terminaison et des méthodes HTTP ;
\n
• les modèles de données (schémas de requêtes et de réponses) ;
\n
• les paramètres (query, path, header) ;
\n
• les informations sur l'authentification et l'autorisation.
\n

La documentation générée via OpenAPI permet de créer automatiquement des SDK clients, d'effectuer des tests et de maintenir la description de l'API à jour. Pour Java, il existe plusieurs solutions matures.

1. SpringDoc OpenAPI (recommandé pour Spring Boot)

SpringDoc est la bibliothèque la plus populaire pour la génération d'OpenAPI 3 dans l'écosystème Spring. Elle analyse automatiquement les contrôleurs, les annotations @RequestMapping, @GetMapping, etc., et construit la spécification à partir de celles-ci.

Ajout de la dépendance (Maven)

<dependency>\n    <groupId>org.springdoc</groupId>\n    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>\n    <version>2.6.0</version>\n</dependency>

Exemple de contrôleur avec annotations

@RestController\n@RequestMapping("/api/users")\npublic class UserController {\n\n    @Operation(summary = "Obtenir un utilisateur par son ID")\n    @ApiResponses(value = {\n        @ApiResponse(responseCode = "200", description = "Utilisateur trouvé"),\n        @ApiResponse(responseCode = "404", description = "Utilisateur non trouvé")\n    })\n    @GetMapping("/{id}")\n    public ResponseEntity<User> getUser(@PathVariable Long id) {\n        // logique métier\n        return ResponseEntity.ok(new User(id, "Ivan", "ivan@example.com"));\n    }\n}

Après le démarrage de l'application, la documentation est accessible à l'adresse /swagger-ui.html, et la spécification au format JSON à /v3/api-docs.

2. Swagger Core (OpenAPI 3.0)

Swagger Core est une bibliothèque de bas niveau créée par les auteurs de la spécification. Elle permet de construire programmatiquement des objets OpenAPI et de les sérialiser en JSON/YAML. Elle convient aux cas où un contrôle fin de la génération est nécessaire.

Exemple de création programmatique d'une spécification

import io.swagger.v3.oas.models.*;\nimport io.swagger.v3.oas.models.info.*;\n\nOpenAPI openAPI = new OpenAPI()\n    .info(new Info()\n        .title("Exemple d'API")\n        .version("1.0.0")\n        .description("Documentation créée manuellement"))\n    .path("/hello", new PathItem()\n        .get(new Operation()\n            .summary("Salutation")\n            .operationId("sayHello")\n            .addParametersItem(new Parameter()\n                .name("name")\n                .in("query")\n                .required(false)\n                .schema(new StringSchema()))\n            .responses(new ApiResponses()\n                .addApiResponse("200", new ApiResponse()\n                    .description("OK")\n                    .content(new Content()\n                        .addMediaType("text/plain", \n                            new MediaType().schema(new StringSchema())))))));\n\n// Sérialisation en JSON\nObjectMapper mapper = new ObjectMapper();\nString json = mapper.writeValueAsString(openAPI);\nSystem.out.println(json);

3. OpenAPI Generator (génération de code à partir d'une spécification)

OpenAPI Generator est un outil qui fonctionne dans le sens inverse