OpenAPI / Swagger Java: Methoden, Beispiele, Installation…

Was ist OpenAPI / Swagger und warum braucht ein Java-Entwickler es?

OpenAPI (früher bekannt als Swagger) ist eine Spezifikation zur Beschreibung, Erstellung, Dokumentation und Nutzung von RESTful APIs. Für Java-Entwickler sind die OpenAPI / Swagger Bibliotheken ein unverzichtbares Werkzeug, das die API-Dokumentation und die Generierung von Client-Code automatisiert.

Die Hauptgründe für den Einsatz von OpenAPI / Swagger in Java-Projekten:

Automatische Dokumentationsgenerierung – Die Bibliothek analysiert Ihren Code (Spring Boot Annotations, JAX-RS) und erstellt eine interaktive Dokumentation im Swagger UI Format.
Standardisierung – Ein einheitliches API-Beschreibungsformat, das sowohl für Menschen als auch für Maschinen verständlich ist.
Client-Code-Generierung – Sie können einen Java-Client für jede in OpenAPI beschriebene API generieren.
Testen – Swagger UI ermöglicht es, API-Anfragen direkt aus dem Browser heraus durchzuführen.
CI/CD-Integration – Sie können die Übereinstimmung der API mit der Spezifikation bereits in der Build-Phase überprüfen.

In diesem Artikel betrachten wir die zwei wichtigsten Java-Bibliotheken: springdoc-openapi (für Spring Boot) und Swagger Core (für JAX-RS und andere Frameworks).

Installation der OpenAPI / Swagger Bibliothek für Java

Die Installation hängt vom verwendeten Framework ab. Wir betrachten die zwei Hauptvarianten.

Variante 1: Spring Boot (springdoc-openapi)

Fügen Sie die Abhängigkeit zu Ihrer pom.xml (Maven) hinzu:

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

Für Gradle (build.gradle):

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

Variante 2: JAX-RS / Jakarta (Swagger Core)

Maven:

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2-jakarta</artifactId>
    <version>2.2.22</version>
</dependency>

Gradle:

implementation 'io.swagger.core.v3:swagger-jaxrs2-jakarta:2.2.22'

Schnellstart: Erstes Beispiel mit Spring Boot

Nachdem Sie die Abhängigkeit springdoc-openapi zu Ihrem Spring Boot Projekt hinzugefügt haben, ist Swagger UI automatisch unter http://localhost:8080/swagger-ui.html verfügbar. Erstellen wir einen einfachen Controller:

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

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

    @GetMapping("/{id}")
    @Operation(summary = "Benutzer nach ID abrufen")
    public String getUser(@PathVariable Long id) {
        return "Benutzer mit ID: " + id;
    }

    @PostMapping
    @Operation(summary = "Neuen Benutzer erstellen")
    public String createUser(@RequestBody String userName) {
        return "Benutzer erstellt: " + userName;
    }
}

Starten Sie die Anwendung und öffnen Sie http://localhost:8080/swagger-ui.html – Sie sehen eine interaktive Dokumentation, mit der Sie direkt Anfragen ausführen können.