Dokumentieren mit OpenAPI
Erzeuge lebendige, interaktive API-Dokumentation mit springdoc-openapi und Swagger UI - kostenlos.
Deutsche Übersetzung in Arbeit
Diese Lektion ist noch nicht ins Deutsche übersetzt und wird daher auf Englisch angezeigt. Der Rest der Seite ist vollständig lokalisiert.
Auf dieser Seite
An API nobody can figure out how to call is only half-built. Hand-written docs rot the moment the code changes. The fix: generate interactive documentation from the code itself, so it's always accurate. In the Spring world that means OpenAPI (the specification) and Swagger UI (a browser interface), added by springdoc.
Add springdoc
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.8.0</version>
</dependency>That single dependency inspects your controllers, DTOs, and validation annotations and produces:
/v3/api-docs- the machine-readable OpenAPI JSON, for code generators and tools./swagger-ui.html- a live, interactive UI where anyone can read the endpoints and try them out in the browser.
Start BookVault and open http://localhost:8080/swagger-ui.html - every endpoint, its
parameters, request/response shapes, and even the validation rules are already there.
A hand-written API doc is like a paper map of a city that's constantly being rebuilt - it's wrong the day after you print it. OpenAPI is like a live GPS map generated from the streets themselves: because it's derived from the actual code, it can't drift out of date. Change a route, and the map updates automatically.
Enrich it with annotations
Springdoc infers a lot on its own, but a few annotations make the docs excellent:
@Operation(summary = "Find a book by ISBN")
@ApiResponse(responseCode = "200", description = "The book")
@ApiResponse(responseCode = "404", description = "No book with that ISBN")
@GetMapping("/{isbn}")
BookResponse byIsbn(@PathVariable String isbn) { ... }You can also set a global title and version:
@Bean
OpenAPI bookVaultApi() {
return new OpenAPI().info(new Info()
.title("BookVault API").version("v1")
.description("A community-library API"));
}Lock it down in production
Swagger UI is wonderful in development but exposes your full API surface. In
production, secure or disable the UI (springdoc.swagger-ui.enabled=false) - or put it
behind authentication, which you'll add in the Security module.
Your team keeps shipping API changes that the separate wiki docs never catch up with, so clients integrate against stale information. Explain how generating OpenAPI from the code solves this, and name the two URLs springdoc exposes and what each is for.
Why is generating OpenAPI docs from your code better than maintaining separate written docs?
Key takeaways
- springdoc-openapi generates OpenAPI docs directly from your controllers, DTOs, and validation - so they stay accurate.
- It exposes /v3/api-docs (machine-readable JSON) and /swagger-ui.html (interactive UI to read and try endpoints).
- Annotations like @Operation and @ApiResponse enrich the generated docs; an OpenAPI bean sets global info.
- Secure or disable Swagger UI in production - it reveals your whole API surface.
- Generated docs can't drift from the code the way hand-written docs do.