giuseppe-trisciuoglio/spring-boot-openapi-documentation

Was macht spring-boot-openapi-documentation?

Stellt Muster zur Verfügung, um umfassende REST-API-Dokumentation mit SpringDoc OpenAPI 3.0 und Swagger UI in Spring Boot 3.x-Anwendungen zu generieren. Verwenden Sie dies beim Einrichten der API-Dokumentation, Konfigurieren der Swagger UI, Hinzufügen von OpenAPI-Annotationen, Implementieren der Sicherheitsdokumentation oder Erweitern von REST-Endpunkten mit Beispielen und Schemas.

Verwendung

Abhängigkeiten

Fügen Sie die folgende Maven-Abhängigkeit zu Ihrer pom.xml hinzu:

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

Für Gradle:

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

Basis-Konfiguration

Erstellen Sie eine Konfigurationsklasse, um SpringDoc anzupassen:

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Meine API")
                        .version("1.0")
                        .description("Dies ist meine Spring Boot 3.x REST-API")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")));
    }
}

Endpunkt-Annotationen

Verwenden Sie OpenAPI-Annotationen, um Ihre REST-Controller zu dokumentieren:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "Benutzer", description = "Benutzerverwaltungs-Endpunkte")
public class UserController {

    @Operation(summary = "Benutzer abrufen", description = "Ruft einen Benutzer anhand seiner ID ab")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Erfolgreich abgerufen"),
        @ApiResponse(responseCode = "404", description = "Benutzer nicht gefunden")
    })
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // Implementierung
        return new User();
    }
}

Modell-Schemas

Dokumentieren Sie Ihre Modelle mit Schema-Annotationen:

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

public class User {

    @Schema(description = "Eindeutige Benutzer-ID", example = "12345")
    private Long id;

    @Schema(description = "Vollständiger Name des Benutzers", example = "Max Mustermann")
    private String name;

    // Getter und Setter
}

Sicherheit (JWT)

Um JWT-Authentifizierung zu dokumentieren, fügen Sie der Konfiguration einen Sicherheitsplan hinzu:

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityScheme;

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .components(new Components().addSecuritySchemes("bearerAuth",
                    new SecurityScheme().type(SecurityScheme.Type.HTTP)
                            .scheme("bearer")
                            .bearerFormat("JWT")))
            .info(new Info().title("Meine API").version("1.0"));
}

Fügen Sie dann die Sicherheitsanforderung auf Endpunktebene mit @SecurityRequirement(name = "bearerAuth") hinzu.

Swagger UI

Greifen Sie nach dem Start der Anwendung auf die Swagger UI unter http://localhost:8080/swagger-ui/index.html zu. Die OpenAPI-Spezifikation ist unter http://localhost:8080/v3/api-docs verfügbar.

Erweiterte Beispiele

Für gültige Beispiele in Antworten:

@Operation(summary = "Benutzer erstellen")
@ApiResponse(responseCode = "201", description = "Benutzer erstellt",
    content = @Content(mediaType = "application/json",
        schema = @Schema(implementation = User.class),
        examples = @ExampleObject(value = "{\"id\":1,\"name\":\"Max\"}")))
@PostMapping
public User createUser(@RequestBody User user) {
    return userService.save(user);
}

Unterstützte Plattformen

• Spring Boot 3.x
• SpringDoc OpenAPI Starter WebMVC UI
• Kompatibel mit Java 17 und höher

Lizenz

Apache 2.0