In modernen Microservices-Architekturen ist die Definition und Dokumentation von APIs essenziell für die Entwicklung, Integration und Wartung von Services. Der Code-First-Ansatz, insbesondere in Spring Boot-Anwendungen, ermöglicht die Generierung von OpenAPI-Contracts direkt aus dem Code. Dieser Ansatz fördert eine agile Entwicklung, bei der die API-Spezifikation parallel zur Implementierung entsteht und sich dynamisch mit ihr weiterentwickelt. In diesem Artikel wird beschrieben, wie Sie aus dem Code eines Spring Boot-Projekts automatisch einen OpenAPI-Contract generieren können.
OpenAPI (früher bekannt als Swagger) ist ein Standard zur Beschreibung von RESTful APIs. Ein OpenAPI-Contract ist eine maschinenlesbare Definition einer API, die Tools für die Generierung von Client-Bibliotheken, Server-Stubs, Dokumentationen und anderen nützlichen Ressourcen bietet.
Der Code-First-Ansatz besteht darin, die API direkt im Code zu definieren und die API-Spezifikation automatisch daraus zu generieren. Dies hat den Vorteil, dass die Dokumentation immer aktuell ist und genau das widerspiegelt, was die API tatsächlich leistet.
Um den Code-First-Ansatz in Spring Boot zu nutzen und einen OpenAPI-Contract zu generieren, können Sie das Springdoc OpenAPI Projekt verwenden. Dieses Projekt bietet Integration mit Spring Boot und automatische Generierung von OpenAPI 3.0-Spezifikationen aus Ihrem Spring-Code.
Fügen Sie die Springdoc OpenAPI-Abhängigkeit zu Ihrem
pom.xml oder build.gradle hinzu. Für
Maven-Projekte:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>{springdoc-version}</version>
</dependency>Für Gradle-Projekte:
implementation 'org.springdoc:springdoc-openapi-ui:{springdoc-version}'Springdoc OpenAPI benötigt keine umfangreiche Konfiguration, um zu
funktionieren. Standardmäßig generiert es die OpenAPI-Spezifikation
basierend auf Ihrem Spring-Code und stellt diese über einen
eingebetteten Endpunkt zur Verfügung, typischerweise
/v3/api-docs.
Sie können jedoch die OpenAPI-Spezifikation weiter anpassen und
verfeinern, indem Sie eine OpenAPI-Bean in einer Ihrer
Konfigurationsklassen definieren:
import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info().title("Mein API-Titel")
.description("Eine detaillierte Beschreibung meiner API")
.version("1.0.0"));
}
}Springdoc OpenAPI nutzt Spring Web Annotations und fügt eigene hinzu, um die OpenAPI-Spezifikation zu bereichern. Hier ein einfaches Beispiel, wie Sie einen REST-Controller mit OpenAPI Annotations annotieren können:
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
@RestController
public class GreetingController {
@GetMapping("/greeting")
@Operation(summary = "Begrüßt den Benutzer", description = "Liefert eine Begrüßungsnachricht für den Benutzer.")
@ApiResponse(responseCode = "200", description = "Erfolgreiche Begrüßung")
public String greeting() {
return "Hallo, Welt!";
}
}Nachdem Sie Ihr Spring Boot-Projekt gestartet haben, ist die
generierte OpenAPI-Dokumentation unter /v3/api-docs in
JSON-Format verfügbar. Für eine benutzerfreundliche Darstellung können
Sie Swagger UI unter /swagger-ui.html aufrufen.