12 OpenAPI / Swagger

12.1 Einführung

OpenAPI, früher bekannt als Swagger, ist eine Spezifikation zur Beschreibung von RESTful APIs. Sie ermöglicht es, APIs in einem standardisierten Format zu definieren, das sowohl von Menschen als auch von Maschinen gelesen werden kann. Durch die Verwendung von OpenAPI können Entwickler APIs klar dokumentieren, testen und automatisiert Code generieren.

12.2 Historischer Kontext

Swagger wurde ursprünglich entwickelt, um die Erstellung, Dokumentation und den Konsum von RESTful Webservices zu vereinfachen. Mit der Zeit wurde Swagger zur OpenAPI Specification (OAS) weiterentwickelt und ist heute ein weit verbreiteter Standard in der API-Entwicklung.

12.3 Vorteile von OpenAPI

• Standardisierung: Einheitliches Format für die Beschreibung von APIs, unabhängig von der Implementierungssprache.
• Automatisierung: Generierung von Client- und Server-Code basierend auf der Spezifikation.
• Dokumentation: Automatisch generierte, interaktive API-Dokumentation erleichtert das Verständnis und die Nutzung der API.
• Validierung: Prüfung der API-Implementierung gegen die Spezifikation zur Sicherstellung der Konformität.

12.4 Struktur einer OpenAPI-Spezifikation

Eine OpenAPI-Spezifikation ist in YAML oder JSON verfasst und besteht aus mehreren Hauptkomponenten:

• Info: Metadaten zur API wie Titel, Beschreibung und Version.
• Servers: Liste der Server, auf denen die API läuft.
• Paths: Definition der verfügbaren Endpunkte und zugehörigen HTTP-Methoden.
• Components: Wiederverwendbare Objekte wie Schemas, Sicherheitsdefinitionen und Parameter.
• Security: Globale Sicherheitsanforderungen der API.
• Tags: Gruppierung von Endpunkten zur besseren Übersichtlichkeit.

12.4.1 Beispiel einer einfachen OpenAPI-Spezifikation

openapi: 3.0.1
info:
  title: Bücher API
  version: 1.0.0
servers:
  - url: http://localhost:8080/api
paths:
  /books:
    get:
      summary: Liste aller Bücher abrufen
      responses:
        '200':
          description: Erfolgreiche Antwort
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        author:
          type: string

12.5 Integration von OpenAPI in Spring Boot

Spring Boot bietet mehrere Möglichkeiten, OpenAPI in Anwendungen zu integrieren:

1. Springdoc OpenAPI

   • Eine Bibliothek zur Unterstützung von OpenAPI 3 für Spring Boot.
   • Automatische Generierung der OpenAPI-Spezifikation basierend auf den vorhandenen Controller-Klassen und Annotationen.

2. Swagger UI

   • Eine visuelle Oberfläche zur Darstellung der API-Dokumentation.
   • Ermöglicht das Testen der API direkt über den Browser.

12.6 Einrichtung von Springdoc OpenAPI

12.6.1 Schritt 1: Abhängigkeiten hinzufügen

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

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

12.6.2 Schritt 2: Anwendung konfigurieren

In den meisten Fällen ist keine zusätzliche Konfiguration notwendig. Springdoc scannt automatisch Ihre REST-Controller und generiert die OpenAPI-Dokumentation.

12.6.3 Zugriff auf die Swagger UI

Nach dem Start der Anwendung kann die API-Dokumentation unter http://localhost:8080/swagger-ui.html oder http://localhost:8080/swagger-ui/index.html aufgerufen werden.

12.6.4 Beispiel eines REST-Controllers mit OpenAPI-Annotationen

import org.springframework.web.bind.annotation.*;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;

@RestController
@RequestMapping("/api/books")
public class BookController {

    @Operation(summary = "Liste aller Bücher abrufen")
    @ApiResponse(responseCode = "200", description = "Erfolgreiche Antwort",
        content = @Content(mediaType = "application/json",
        schema = @Schema(implementation = Book.class)))
    @GetMapping
    public List<Book> getAllBooks() {
        // Implementierung
    }

    @Operation(summary = "Ein Buch anhand der ID abrufen")
    @ApiResponse(responseCode = "200", description = "Buch gefunden",
        content = @Content(mediaType = "application/json",
        schema = @Schema(implementation = Book.class)))
    @ApiResponse(responseCode = "404", description = "Buch nicht gefunden")
    @GetMapping("/{id}")
    public ResponseEntity<Book> getBookById(@PathVariable Long id) {
        // Implementierung
    }

    // Weitere Methoden
}

12.6.5 Erläuterung der Annotationen

• @Operation: Beschreibt die API-Operation und bietet Metadaten wie eine Zusammenfassung.
• @ApiResponse: Definiert mögliche Antworten, ihren HTTP-Statuscode und optionalen Inhalt.
• @Content: Gibt den Medientyp und das zugehörige Schema für die Antwort an.
• @Schema: Beschreibt das Datenmodell, das in der Antwort verwendet wird.

12.6.6 Definieren von Datenmodellen

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "Repräsentiert ein Buch im System")
public class Book {

    @Schema(description = "Eindeutige ID des Buches", example = "1")
    private Long id;

    @Schema(description = "Titel des Buches", example = "Spring Boot in Action")
    private String title;

    @Schema(description = "Autor des Buches", example = "Craig Walls")
    private String author;

    // Getter und Setter
}

12.7 Contract First vs. Code First

• Code First: Der Entwickler schreibt zunächst den Anwendungscode (Controller, Modelle) und generiert daraus die OpenAPI-Spezifikation.
• Contract First: Die API-Spezifikation wird zuerst erstellt, und der Anwendungscode wird basierend auf dieser Spezifikation generiert.

12.8 Schwerpunkt auf Contract-First-Ansatz

Beim Contract-First-Ansatz steht die API-Spezifikation im Zentrum der Entwicklung. Dies bietet mehrere Vorteile:

• Klar definierte Schnittstellen: Alle Beteiligten (Entwickler, Tester, Kunden) arbeiten auf Basis derselben Spezifikation.
• Unabhängige Entwicklung: Frontend- und Backend-Teams können parallel arbeiten.
• Frühe Validierung: Designfehler können frühzeitig erkannt und behoben werden.

12.9 Implementierung des Contract-First-Ansatzes

12.9.1 Schritt 1: OpenAPI-Spezifikation erstellen

Erstellen Sie eine OpenAPI-Spezifikation in einer YAML- oder JSON-Datei (api.yaml), die alle Endpunkte, Modelle und Sicherheitsaspekte Ihrer API definiert.

12.9.2 Schritt 2: Code-Generierung

Verwenden Sie Werkzeuge wie OpenAPI Generator oder Swagger Codegen, um aus der Spezifikation Server-Stubs und Modelle zu generieren.

12.9.3 Beispiel: Generierung mit OpenAPI Generator

Installieren Sie den OpenAPI Generator:

brew install openapi-generator

Oder über Docker:

docker pull openapitools/openapi-generator-cli

Führen Sie die Code-Generierung aus:

openapi-generator generate -i api.yaml -g spring -o generated-server

12.9.3.1 Parameter

• -i: Pfad zur OpenAPI-Spezifikationsdatei.
• -g: Zielplattform, hier spring für einen Spring Boot Server.
• -o: Ausgabeverzeichnis für den generierten Code.

12.9.4 Schritt 3: Implementierung der Geschäftslogik

Die generierten Stubs enthalten Methoden, die Sie mit der eigentlichen Geschäftslogik füllen müssen.

12.9.5 Vorteile des Contract-First-Ansatzes

• Konsistenz: Die Implementierung bleibt immer synchron mit der Spezifikation.
• Automatisierung: Reduziert manuelle Fehler durch automatische Code-Generierung.
• Effizienz: Beschleunigt die Entwicklung durch klare Vorgaben.

12.9.6 Herausforderungen

• Initialer Aufwand: Erstellung und Pflege der Spezifikation erfordert Disziplin und klare Prozesse.
• Abhängigkeit von Tools: Die Qualität des generierten Codes hängt von den verwendeten Tools ab.

12.10 Best Practices

• Versionskontrolle der Spezifikation

  Verwalten Sie die OpenAPI-Spezifikation im gleichen Repository wie den Code, um Änderungen nachvollziehen zu können.

• Automatisierte Tests

  Implementieren Sie Tests, die sicherstellen, dass die Implementierung der Spezifikation entspricht.

• Kontinuierliche Integration

  Integrieren Sie die Code-Generierung und Validierung in Ihre CI/CD-Pipeline.

12.11 Integration mit Build-Tools

12.11.1 Maven Plugin Beispiel

Fügen Sie das OpenAPI Generator Maven Plugin zu Ihrer pom.xml hinzu:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.4.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <output>${project.build.directory}/generated-sources</output>
            </configuration>
        </execution>
    </executions>
</plugin>

12.12 Zusammenfassung der Vorteile von OpenAPI

• Klarheit und Transparenz: Die API ist eindeutig definiert, was Kommunikation und Zusammenarbeit erleichtert.
• Automatisierung: Reduziert manuellen Aufwand durch automatische Code-Generierung.
• Qualitätssicherung: Durch Validierung gegen die Spezifikation werden Implementierungsfehler minimiert.

12.13 tl;dr

OpenAPI / Swagger ermöglicht die standardisierte Beschreibung von RESTful APIs, was Dokumentation, Testing und Code-Generierung erleichtert. Der Contract-First-Ansatz stellt die Spezifikation in den Mittelpunkt und fördert konsistente und effiziente API-Entwicklung. Durch Integration von Tools wie Springdoc OpenAPI können Entwickler in Spring Boot Anwendungen nahtlos OpenAPI nutzen.