API Documentation with OpenAPI / Swagger
A Kafka-backed REST API is still a REST API — clients need to discover and try it without reading your source code.
Learning objectives
- Beginner: Explain why a Kafka-backed service still needs OpenAPI/Swagger documentation like any other REST API.
- Intermediate: Add Swagger annotations to a producer's REST endpoints so its contract is discoverable without reading the source.
- Advanced: Keep generated API docs accurate as the producer's DTOs evolve, without manually maintaining a separate spec file.
◆ The problem
Traditional API docs (a wiki page, a Postman collection someone forgot to update) drift out of sync with the actual code. For a producer whose entire job is "accept this exact JSON shape and route it correctly by key," an out-of-date example is worse than no example — a client following stale docs sends a malformed LibraryEvent that either fails validation or, worse, publishes a record the consumer can't deserialize downstream.
OpenAPI 3 generates the API description directly from your controller and DTO annotations, so the docs and the code can't drift apart — the spec is derived from the same @Valid / @NotBlank annotations from Module 06, not a hand-maintained duplicate of them.
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.6.0</version> </dependency>
No further configuration is required for a working baseline — the dependency alone exposes an interactive UI at /swagger-ui.html and the machine-readable spec at /v3/api-docs, both generated from your existing @RestController /DTO annotations.
@Operation(summary = "Publish a new library event", description = "Publishes an unkeyed NEW LibraryEvent to the library-events topic.") @ApiResponse(responseCode = "201", description = "Event accepted and published") @ApiResponse(responseCode = "400", description = "Validation failed") @PostMapping("/libraryevent") public ResponseEntity<LibraryEvent> createEvent(@Valid @RequestBody LibraryEvent libraryEvent) { ... }
✓ Quick recap
Where does springdoc-openapi get its documentation content from? Directly from your controller and DTO annotations, so it can't drift from the actual validation rules. What two endpoints does adding the dependency give you by default? An interactive UI (/swagger-ui.html) and a machine-readable spec (/v3/api-docs).
💻 Code example
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.6.0</version> </dependency>
Want a visual for this concept?
Generate a diagram tailored to “API Documentation with OpenAPI / Swagger” — the AI picks whichever visual (flowchart, comparison, sequence, etc.) best fits.
Sign in to generate a visual →