Swagger/OpenAPI-Generierung für Java: Die besten Bibliotheken

Swagger/OpenAPI-Generierung für Java: Vollständiger Leitfaden zu den Werkzeugen

In der modernen Java-Entwicklung ist die Erstellung einer qualitativ hochwertigen API-Dokumentation zu einem wesentlichen Bestandteil des Prozesses geworden. Die OpenAPI-Spezifikation (früher bekannt als Swagger) bietet ein standardisiertes Format zur Beschreibung von RESTful-APIs. In diesem Artikel betrachten wir die wichtigsten Werkzeuge zur Generierung von Swagger/OpenAPI-Dokumentation in Java-Projekten, ihre Besonderheiten und Anwendungsbeispiele.

Was sind Swagger und OpenAPI?

Swagger ist eine Sammlung von Werkzeugen zum Entwerfen, Erstellen und Dokumentieren von REST-APIs. OpenAPI ist eine Spezifikation, die den Standard zur Beschreibung von APIs definiert. Swagger ist die bekannteste Implementierung dieser Spezifikation.

Wichtige Bibliotheken für Java

Wir betrachten drei zentrale Werkzeuge:

• SpringDoc OpenAPI – eine moderne Bibliothek für Spring Boot
• Swagger Core – die grundlegende Bibliothek der Swagger-Entwickler
• OpenAPI Generator – ein Werkzeug zur Code- und Dokumentationsgenerierung

1. SpringDoc OpenAPI

SpringDoc ist die beliebteste Wahl für Projekte mit Spring Boot. Es integriert sich automatisch in Ihre Anwendung und generiert Dokumentation basierend auf Annotationen und Datentypen.

Installation und Konfiguration

Fügen Sie die Abhängigkeit in pom.xml hinzu:

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

Anwendungsbeispiel

Erstellen Sie einen einfachen Controller mit Dokumentation:

@RestController@RequestMapping("/api/users")@Tag(name = "Benutzer", description = "Benutzerverwaltung")public class UserController {

    @GetMapping("/{id}")    @Operation(summary = "Benutzer nach ID abrufen")    public ResponseEntity<User> getUser(            @Parameter(description = "Benutzer-ID")            @PathVariable Long id) {        // Implementierung        return ResponseEntity.ok(new User(id, "Ivan"));    }

    @PostMapping    @Operation(summary = "Neuen Benutzer erstellen")    public ResponseEntity<User> createUser(            @RequestBody @Valid CreateUserRequest request) {        // Implementierung        return ResponseEntity.status(201).body(new User(1L, request.getName()));    }}

Nach dem Start der Anwendung ist die Dokumentation unter http://localhost:8080/swagger-ui.html verfügbar.

2. Swagger Core

Die Bibliothek Swagger Core bietet einen eher low-level Ansatz zur Erstellung der OpenAPI-Spezifikation. Sie eignet sich für Projekte, bei denen vollständige Kontrolle über die Generierung erforderlich ist.

Beispiel zur manuellen Erstellung einer Spezifikation

import io.swagger.v3.oas.models.*;import io.swagger.v3.oas.models.info.*;

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("Pet Store API")        .description("API zur Verwaltung von Haustieren")        .version("1.0.0")        .contact(new Contact()            .name("Entwickler")            .email("dev@example.com")))    .addServersItem(new Server()        .url("https://api.example.com/v1")        .description("Produktionsserver"));

// Hinzufügen von Pfaden und KomponentenPaths paths = new Paths();paths.addPathItem("/pets", new PathItem()    .get(new Operation()        .operationId("listPets")        .summary("Liste der Haustiere abrufen")));openAPI.setPaths(paths);

3. OpenAPI Generator

OpenAPI Generator ist ein Werkzeug, das sowohl Dokumentation als auch Client-/Server-Code basierend auf der OpenAPI-Spezifikation generieren kann.

Verwendung in Maven

Fügen Sie das Plugin in pom.