Java einfach erklärt

Plain Java Spring

Nutzung von OpenAPI in Java

Einführung

OpenAPI, früher bekannt als Swagger, ist eine weit verbreitete Spezifikation zur Beschreibung von RESTful APIs. Es ermöglicht Entwicklern, die Struktur ihrer APIs in einem standardisierten Format zu definieren, was die Interoperabilität zwischen verschiedenen Systemen und Technologien erleichtert. In der Java-Entwicklung spielt OpenAPI eine wichtige Rolle bei der Dokumentation, Generierung und Validierung von API-Schnittstellen.

Was ist OpenAPI?

OpenAPI ist eine Spezifikation für maschinenlesbare Schnittstellen von Webservices. Es beschreibt die verfügbaren Endpunkte, deren Parameter, Rückgabewerte und andere Aspekte einer API. Das Format ist JSON- oder YAML-basiert, was es sowohl menschen- als auch maschinenlesbar macht. Mit der OpenAPI-Spezifikation kann ein breites Spektrum an Werkzeugen genutzt werden, um Dokumentation zu generieren, Code zu erzeugen oder Tests durchzuführen.

OpenAPI in der Java-Entwicklung

In der Java-Entwicklung gibt es verschiedene Bibliotheken und Frameworks, die die Integration von OpenAPI unterstützen. Diese Tools vereinfachen die Erstellung, Wartung und Nutzung von APIs erheblich. Zu den bekanntesten gehören Swagger, Springfox, und OpenAPI Generator.

Swagger und Springfox

Swagger ist das bekannteste Toolset zur Nutzung der OpenAPI-Spezifikation. Es bietet eine Reihe von Tools, darunter Swagger Editor, Swagger UI und Swagger Codegen. Springfox ist eine Bibliothek, die die Integration von Swagger in Spring Boot-Anwendungen erleichtert.

Einrichtung von Springfox in einem Spring Boot-Projekt

Um Springfox in ein Spring Boot-Projekt zu integrieren, müssen einige Abhängigkeiten in der pom.xml-Datei hinzugefügt werden:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>Code-Sprache: HTML, XML (xml)

Nach dem Hinzufügen der Abhängigkeiten kann die Konfiguration der API-Dokumentation beginnen. Dies geschieht durch die Erstellung einer Konfigurationsklasse:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api"))
                .build();
    }
}Code-Sprache: CSS (css)

Diese Konfiguration scannt alle Controller im Paket com.example.api und generiert automatisch die OpenAPI-Dokumentation. Die generierte Dokumentation kann dann unter http://localhost:8080/swagger-ui/ aufgerufen werden.

OpenAPI Generator

Der OpenAPI Generator ist ein weiteres mächtiges Werkzeug, das aus einer OpenAPI-Spezifikation Client- und Servercode für verschiedene Programmiersprachen generieren kann, einschließlich Java. Es bietet zahlreiche Generatoren für unterschiedliche Frameworks wie Spring, JAX-RS und viele mehr.

Verwendung des OpenAPI Generators

Um den OpenAPI Generator zu nutzen, muss die OpenAPI-Spezifikation in einer JSON- oder YAML-Datei vorliegen. Angenommen, wir haben eine openapi.yaml-Datei, die unsere API beschreibt. Mit dem folgenden Befehl kann ein Spring Boot-Projekt generiert werden:

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

Dieser Befehl verwendet den OpenAPI Generator CLI, um den Servercode basierend auf der OpenAPI-Spezifikation zu erzeugen. Der -i Parameter gibt die Eingabedatei an, -g spezifiziert den gewünschten Generator (in diesem Fall spring), und -o gibt das Ausgabeverzeichnis an.

Praktische Anwendung

Dokumentation

Eine der Hauptanwendungen von OpenAPI ist die Dokumentation von APIs. Durch die Nutzung von Swagger UI oder anderen Tools können Entwickler und Anwender eine interaktive Dokumentation erstellen, die es ermöglicht, Endpunkte direkt auszuprobieren.

Codegenerierung

Ein weiteres nützliches Feature ist die Codegenerierung. Mit Tools wie OpenAPI Generator können Entwickler sowohl Server- als auch Clientcode aus einer einzigen Spezifikation generieren. Dies spart Zeit und reduziert das Risiko von Inkonsistenzen zwischen verschiedenen Implementierungen.

Validierung

OpenAPI kann auch zur Validierung von API-Anfragen und -Antworten verwendet werden. Frameworks wie Spring bieten Middleware an, die eingehende Anfragen gegen die OpenAPI-Spezifikation validiert und sicherstellt, dass sie den definierten Anforderungen entsprechen.

Beispiel: Erstellung einer RESTful API mit OpenAPI und Spring Boot

Im Folgenden wird ein vollständiges Beispiel gezeigt, wie eine RESTful API mit OpenAPI und Spring Boot erstellt wird.

Schritt 1: Projekt einrichten

Erstellen Sie ein neues Spring Boot-Projekt mit den folgenden Abhängigkeiten in der pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>Code-Sprache: HTML, XML (xml)

Schritt 2: API-Controller erstellen

Erstellen Sie einen einfachen Controller, um eine RESTful API zu definieren:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class HelloWorldController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World!";
    }
}Code-Sprache: CSS (css)

Schritt 3: Swagger-Konfiguration hinzufügen

Fügen Sie die Swagger-Konfigurationsklasse hinzu, um die Dokumentation zu aktivieren:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api"))
                .build();
    }
}Code-Sprache: CSS (css)

Schritt 4: OpenAPI-Dokumentation generieren

Starten Sie die Anwendung und rufen Sie die Swagger-UI unter http://localhost:8080/swagger-ui/ auf, um die generierte Dokumentation zu sehen. Sie können die API-Endpunkte ausprobieren und die Dokumentation automatisch aktualisieren lassen.

Fazit

OpenAPI bietet eine leistungsstarke Möglichkeit, RESTful APIs zu dokumentieren, zu validieren und zu generieren. In der Java-Entwicklung vereinfachen Tools wie Swagger und OpenAPI Generator die Arbeit erheblich, indem sie den Entwicklungsprozess standardisieren und automatisieren. Die Verwendung von OpenAPI trägt zur Verbesserung der Codequalität und der Zusammenarbeit zwischen Teams bei, indem sie klare und einheitliche API-Spezifikationen bereitstellt.