Swagger/OpenAPI-Generierung für Java: Bibliotheken und Werkzeuge

Swagger/OpenAPI-Generierung für Java: vollständige Übersicht über Werkzeuge und Bibliotheken

Moderne REST-API-Entwicklung in Java ist ohne qualitativ hochwertige Dokumentation undenkbar. Der OpenAPI-Standard (früher bekannt als Swagger Specification) hat sich zum De-facto-Industriestandard für die Beschreibung von HTTP-APIs entwickelt. In diesem Artikel werden wir die wichtigsten Bibliotheken und Werkzeuge zur Generierung von OpenAPI-Spezifikationen in Java-Anwendungen, ihre Funktionen, Anwendungsbeispiele und Auswahlkriterien im Detail besprechen.

Was ist OpenAPI und warum wird es benötigt?

OpenAPI ist eine Spezifikation, die RESTful-APIs im JSON- oder YAML-Format beschreibt. Sie umfasst:

\n
• eine Liste von Endpunkten und HTTP-Methoden;
\n
• Datenmodelle (Schemata für Anfragen und Antworten);
\n
• Parameter (query, path, header);
\n
• Informationen zur Authentifizierung und Autorisierung.
\n

Die gemäß OpenAPI generierte Dokumentation ermöglicht die automatische Erstellung von Client-SDKs, das Durchführen von Tests und die Aktualität der API-Beschreibung. Für Java gibt es mehrere ausgereifte Lösungen.

1. SpringDoc OpenAPI (empfohlen für Spring Boot)

SpringDoc ist die beliebteste Bibliothek zur Generierung von OpenAPI 3 im Spring-Ökosystem. Sie scannt automatisch Controller, Annotationen wie @RequestMapping, @GetMapping usw. und erstellt auf deren Grundlage die Spezifikation.

Einbindung (Maven)

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

Beispiel-Controller mit Annotationen

@RestController\n@RequestMapping("/api/users")\npublic class UserController {\n\n    @Operation(summary = "Benutzer nach ID abrufen")\n    @ApiResponses(value = {\n        @ApiResponse(responseCode = "200", description = "Benutzer gefunden"),\n        @ApiResponse(responseCode = "404", description = "Benutzer nicht gefunden")\n    })\n    @GetMapping("/{id}")\n    public ResponseEntity<User> getUser(@PathVariable Long id) {\n        // Logik\n        return ResponseEntity.ok(new User(id, "Ivan", "ivan@example.com"));\n    }\n}

Nach dem Start der Anwendung ist die Dokumentation unter /swagger-ui.html und die Spezifikation im JSON-Format unter /v3/api-docs verfügbar.

2. Swagger Core (OpenAPI 3.0)

Swagger Core ist eine Low-Level-Bibliothek der Ersteller der Spezifikation. Sie ermöglicht die programmatische Erstellung von OpenAPI-Objekten und deren Serialisierung in JSON/YAML. Geeignet für Fälle, in denen eine feine Steuerung der Generierung erforderlich ist.

Beispiel für die programmatische Erstellung einer Spezifikation

import io.swagger.v3.oas.models.*;\nimport io.swagger.v3.oas.models.info.*;\n\nOpenAPI openAPI = new OpenAPI()\n    .info(new Info()\n        .title("Beispiel-API")\n        .version("1.0.0")\n        .description("Manuell erstellte Dokumentation"))\n    .path("/hello", new PathItem()\n        .get(new Operation()\n            .summary("Begrüßung")\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// Serialisierung in JSON\nObjectMapper mapper = new ObjectMapper();\nString json = mapper.writeValueAsString(openAPI);\nSystem.out.println(json);

3. OpenAPI Generator (Codegenerierung aus Spezifikation)

OpenAPI Generator ist ein Werkzeug, das in umgekehrter Richtung arbeitet