OpenAPI: Schnittstellendokumentation

Mit OpenAPI kannst Du die REST-APIs Deiner Spring Boot-Anwendung einfach und standardisiert dokumentieren. Hier sind die grundlegenden Schritte, um OpenAPI in Deinem Projekt zu verwenden:

Einrichtung

Füge die benötigten Abhängigkeite in deine pom.xml oder build.gradle ein. Prüfe, ob die Version noch aktuell ist:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.3</version>
</dependency>

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.3'

Starte deine Anwendung neu, und die OpenAPI-Dokumentation ist unter /swagger-ui.html oder /swagger-ui/index.html verfügbar.

Wichtige Annotationen

@OpenAPIDefinition: Verwende diese Annotation auf Klassenebene, um grundlegende Informationen über deine API bereitzustellen, wie z. B. Titel, Beschreibung und Version.

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;

@OpenAPIDefinition(info = @Info(title = "My API", version = "1.0", description = "My API for managing contracts"))
@SpringBootApplication
public class MyApplication {
  // ...
}

@Tag: Verwende diese Annotation auf Controller-Ebene, um die verschiedenen Teile Deiner API zu organisieren und zu gruppieren.

import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/contracts")
@Tag(name = "Contracts", description = "Manage contracts")
public class ContractController {
  // ...
}

@Operation: Verwende diese Annotation auf Methodenebene, um eine Beschreibung, Zusammenfassung und andere Details für eine bestimmte API-Operation bereitzustellen.

import io.swagger.v3.oas.annotations.Operation;

@GetMapping("/{id}")
@Operation(summary = "Get a contract by ID", description = "Fetch the details of a specific contract")
public ResponseEntity<Contract> getContractById(@PathVariable Long id) {
  // ...
}

@Parameter: Verwende diese Annotation, um Informationen zu den Parametern Deiner API-Methoden bereitzustellen, z. B. Beschreibung, erforderlich oder nicht, und Beispiele.

import io.swagger.v3.oas.annotations.Parameter;

@GetMapping("/{id}")
public ResponseEntity<Contract> getContractById(
        @Parameter(description = "The unique identifier of the contract") @PathVariable Long id) {
  // ...
}

Indem Du diese Annotationen verwendest, kannst du deine Spring Boot REST-APIs effektiv mit OpenAPI dokumentieren und eine benutzerfreundliche Dokumentation für andere Entwickler bereitstellen.

OpenAPI: Schnittstellendokumentation

Einrichtung

Wichtige Annotationen

Weiterführende Links