OpenAPI, früher bekannt als Swagger, ist eine offene Spezifikation zur Beschreibung von RESTful APIs. Es bietet einen standardisierten Weg, APIs zu definieren, sodass sowohl Menschen als auch Maschinen diese verstehen, dokumentieren, testen und nutzen können. OpenAPI erleichtert die Entwicklung, Wartung und Integration von APIs erheblich, indem es klare Verträge zwischen Dienstleistern und Verbrauchern schafft.
Die Entwicklung von OpenAPI begann ursprünglich mit dem Swagger-Projekt, das von Tony Tam ins Leben gerufen wurde. Swagger gewann schnell an Popularität als Werkzeug zur Dokumentation und Visualisierung von APIs. Im Jahr 2016 übernahm die Linux Foundation das Projekt und gründete die OpenAPI Initiative (OAI), um die Spezifikation als offenen Standard weiterzuentwickeln. Seitdem hat sich OpenAPI zu einem weit verbreiteten Standard in der API-Entwicklung etabliert.
OpenAPI Specification (OAS)
Die OpenAPI Specification ist das Herzstück von OpenAPI. Sie definiert die Struktur und die Bestandteile einer API-Dokumentation. Die Spezifikation kann in YAML- oder JSON-Format verfasst werden und umfasst mehrere Schlüsselkomponenten:
Endpoints und Operationen
Jeder Endpunkt (path) in einer OpenAPI-Spezifikation
repräsentiert eine Ressource oder eine Funktion der API. Innerhalb jedes
Endpunkts werden verschiedene Operationen (HTTP-Methoden wie GET, POST,
PUT, DELETE) definiert, die beschreiben, welche Aktionen auf dieser
Ressource durchgeführt werden können.
Schemas
Schemas definieren die Struktur der Daten, die von der API gesendet und empfangen werden. Sie basieren auf JSON Schema und ermöglichen die präzise Beschreibung von Datenmodellen, einschließlich Typen, Eigenschaften, Validierungen und Beziehungen.
Sicherheitsmechanismen
OpenAPI unterstützt verschiedene Authentifizierungs- und Autorisierungsmethoden, wie API-Schlüssel, OAuth2 und JWT. Diese werden in der Spezifikation definiert und können für einzelne Endpunkte oder global für die gesamte API angewendet werden.
Eine typische OpenAPI-Spezifikation besteht aus den folgenden Hauptkomponenten:
openapi: 3.0.1
info:
title: Bücher API
description: Eine API zur Verwaltung von Büchern.
version: 1.0.0
servers:
- url: https://api.beispiel.com/v1
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'
post:
summary: Ein neues Buch erstellen
requestBody:
description: Buchdaten
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Book'
responses:
'201':
description: Buch erstellt
content:
application/json:
schema:
$ref: '#/components/schemas/Book'
components:
schemas:
Book:
type: object
properties:
id:
type: integer
format: int64
title:
type: string
author:
type: string
required:
- title
- authorSpring Boot bietet mehrere Möglichkeiten, OpenAPI in Anwendungen zu integrieren, um die API-Dokumentation und -Entwicklung zu erleichtern. Eine der beliebtesten Bibliotheken hierfür ist Springdoc OpenAPI.
Fügen Sie die folgende Abhängigkeit zu Ihrer pom.xml
hinzu:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.14</version>
</dependency>Springdoc OpenAPI scannt automatisch Ihre REST-Controller und generiert die OpenAPI-Spezifikation sowie eine interaktive Swagger UI zur Visualisierung und Interaktion mit Ihrer API.
Nach dem Start Ihrer Anwendung können Sie die Swagger UI unter
http://localhost:8080/swagger-ui.html oder
http://localhost:8080/swagger-ui/index.html aufrufen. Diese
Oberfläche ermöglicht es Ihnen, die API-Endpunkte zu erkunden, Anfragen
zu senden und Antworten zu überprüfen.
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
}
@Operation(summary = "Ein neues Buch erstellen")
@ApiResponse(responseCode = "201", description = "Buch erstellt",
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = Book.class)))
@PostMapping
public ResponseEntity<Book> createBook(@RequestBody Book book) {
// Implementierung
}
// Weitere Methoden
}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
}Bei der API-Entwicklung gibt es zwei Hauptansätze zur Nutzung von OpenAPI:
Code First: Der Entwickler schreibt zunächst den Anwendungscode (Controller, Modelle) und generiert daraus die OpenAPI-Spezifikation. Dies ist oft schneller für kleinere Projekte oder wenn die API sich häufig ändert.
Contract First: Die API-Spezifikation wird zuerst erstellt, und der Anwendungscode wird basierend auf dieser Spezifikation generiert. Dies fördert eine klare Trennung zwischen API-Design und Implementierung und ist besonders nützlich in großen Teams oder bei der Zusammenarbeit mit externen Partnern.
Erstellen Sie eine api.yaml-Datei mit der Definition
Ihrer API.
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'
post:
summary: Ein neues Buch erstellen
requestBody:
description: Buchdaten
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Book'
responses:
'201':
description: Buch erstellt
content:
application/json:
schema:
$ref: '#/components/schemas/Book'
components:
schemas:
Book:
type: object
properties:
id:
type: integer
format: int64
title:
type: string
author:
type: string
required:
- title
- authorVerwenden Sie den OpenAPI Generator, um Server-Stubs und Modelle zu generieren.
openapi-generator generate -i api.yaml -g spring -o generated-serverFüllen Sie die generierten Controller-Methoden mit der eigentlichen Geschäftslogik.
Versionskontrolle der Spezifikation
Speichern Sie Ihre OpenAPI-Spezifikation im gleichen Repository wie Ihren Code, um Änderungen nachverfolgen zu können.
Konsistente Nutzung von Tags und Schemas
Verwenden Sie konsistente Namenskonventionen und Strukturen in Ihren Schemas und Tags, um die Lesbarkeit und Wartbarkeit zu erhöhen.
Automatisierte Tests
Implementieren Sie Tests, die sicherstellen, dass die API-Implementierung mit der Spezifikation übereinstimmt.
Integration in die CI/CD-Pipeline
Automatisieren Sie die Code-Generierung und Validierung der Spezifikation in Ihrer Continuous Integration/Continuous Deployment (CI/CD)-Pipeline.
Dokumentation und Pflege
Halten Sie Ihre OpenAPI-Spezifikation stets aktuell und dokumentieren Sie alle Änderungen sorgfältig, um die Qualität der API-Dokumentation zu gewährleisten.
Fügen Sie das OpenAPI Generator Maven Plugin zu Ihrer
pom.xml hinzu, um die Code-Generierung während des
Build-Prozesses zu automatisieren.
<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>Nutzen Sie Springdoc OpenAPI für nahtlose Integration
Springdoc OpenAPI bietet eine einfache Integration mit Spring Boot und ermöglicht die automatische Generierung der OpenAPI-Dokumentation basierend auf Ihren REST-Controllern.
Verwenden Sie aussagekräftige Beschreibungen und Beispiele
Ergänzen Sie Ihre API-Spezifikation mit detaillierten Beschreibungen und Beispielen, um die Verständlichkeit und Benutzerfreundlichkeit zu erhöhen.
Verwalten Sie API-Versionen sorgfältig
Planen Sie eine klare Versionierungsstrategie, um Kompatibilitätsprobleme zu vermeiden und die Weiterentwicklung Ihrer API zu erleichtern.
Nutzen Sie Sicherheitsdefinitionen
Definieren Sie Authentifizierungs- und Autorisierungsschemata in Ihrer OpenAPI-Spezifikation, um die Sicherheitsanforderungen Ihrer API klar zu kommunizieren.
Erstellen Sie konsistente und wiederverwendbare Schemas
Vermeiden Sie Redundanzen, indem Sie wiederverwendbare Schemas für häufig genutzte Datenstrukturen definieren.
OpenAPI ist ein standardisiertes Format zur Beschreibung von RESTful APIs, das die Entwicklung, Dokumentation und Integration von APIs vereinfacht. Mit Komponenten wie Endpunkten, Schemas und Sicherheitsdefinitionen ermöglicht OpenAPI klare Verträge zwischen Dienstleistern und Verbrauchern. Durch die Integration mit Tools wie Springdoc OpenAPI und dem OpenAPI Generator können Entwickler automatisch Client- und Server-Code sowie interaktive Dokumentationen erstellen. OpenAPI fördert die Konsistenz, Automatisierung und Wartbarkeit von APIs, wodurch es zu einem unverzichtbaren Bestandteil moderner API-Entwicklung geworden ist.