API Docs with OpenAPI & springdoc
Add springdoc-openapi and get an interactive Swagger UI at /swagger-ui.html plus a machine-readable spec at /v3/api-docs — then enrich it with a few annotations.
Learn API Docs with OpenAPI & springdoc in our free Java course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a…
Part of the free Java course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.
You should have built REST controllers and DTOs and applied your database migrations with Flyway . Comfort with @RestController and @GetMapping is assumed.
💡 Analogy: A good shop has a catalogue listing every product with a photo, description and price. OpenAPI is that catalogue for your API, and springdoc is a clerk who walks the shelves (your controllers) and writes the catalogue for you. Annotations like @Operation and @Schema are the captions you add so each entry reads well.
You write the endpoints; springdoc writes — and keeps current — the documentation.
Add the springdoc starter and restart. You immediately get /swagger-ui.html and /v3/api-docs — no extra code required.
springdoc infers paths and parameters automatically; these annotations add summaries, response details and grouping so the docs read clearly.
Add @Schema to a model and its fields to give each property a description and an example — both appear in Swagger UI and in the JSON spec.
Swagger UI is just a viewer over this JSON. Tools consume /v3/api-docs directly to generate clients, mocks and contract tests.
To make the spec-from-metadata idea tangible, here is a plain-Java stand-in that turns endpoint metadata into a machine-readable description — with real output.
Answer: at /v3/api-docs — the machine-readable description tools consume.
Answer: @Schema , with a description and example.
You now know how springdoc-openapi auto-generates an OpenAPI 3 spec and Swagger UI, where to find them (/swagger-ui.html and /v3/api-docs), how to enrich docs with @Operation, @ApiResponse, @Tag and @Schema, and why a machine-readable description is so valuable.
Next up: Async & Scheduled Tasks — offloading work and running jobs on a timer.
Practice quiz
What does springdoc-openapi provide for a Spring Boot app?
- Auto-generated OpenAPI docs and a Swagger UI
- A logging backend
- A build tool
- A database driver
Answer: Auto-generated OpenAPI docs and a Swagger UI. springdoc-openapi inspects your controllers at runtime and produces an OpenAPI 3 description plus an interactive Swagger UI, with almost no configuration.
What is the OpenAPI specification?
- A database migration tool
- A unit-testing library
- A standard, machine-readable format for describing REST APIs
- A Java web framework
Answer: A standard, machine-readable format for describing REST APIs. OpenAPI (formerly Swagger) is a language-agnostic, machine-readable standard for describing the endpoints, parameters, schemas and responses of a REST API.
At what URL is the Swagger UI served by default with springdoc?
- /docs
- /swagger-ui.html
- /openapi
- /api/swagger
Answer: /swagger-ui.html. springdoc serves the interactive Swagger UI at /swagger-ui.html by default, which redirects to the bundled UI page.
Where does springdoc expose the raw OpenAPI JSON description?
- /swagger.json
- /api/openapi.yaml
- /docs/json
- /v3/api-docs
Answer: /v3/api-docs. The machine-readable OpenAPI JSON is served at /v3/api-docs by default; a YAML variant is also available.
Which annotation describes a single endpoint operation (summary, description)?
- @Operation
- @Bean
- @Schema
- @Tag
Answer: @Operation. @Operation documents one endpoint method, letting you set its summary and a longer description shown in Swagger UI.
Which annotation documents a specific HTTP status outcome of an endpoint?
- @Transactional
- @ApiResponse
- @RequestMapping
- @Component
Answer: @ApiResponse. @ApiResponse describes one possible response, typically a status code such as 200 or 404 plus its meaning and body schema.
Which annotation groups related endpoints under a heading in Swagger UI?
- @Section
- @Category
- @Group
- @Tag
Answer: @Tag. @Tag attaches a named group (often at the controller level) so related operations appear together in the UI.
Which annotation documents a field of a DTO/model?
- @Valid
- @Column
- @Schema
- @JsonProperty
Answer: @Schema. @Schema (from io.swagger.v3.oas.annotations.media) documents a model or one of its fields with a description, example and constraints.
Why does a machine-readable API description matter?
- It encrypts traffic
- It lets tools generate clients, mock servers and tests automatically
- It replaces the database
- It makes the JVM faster
Answer: It lets tools generate clients, mock servers and tests automatically. Because the OpenAPI document is structured data, tooling can generate typed client SDKs, mock servers, contract tests and live docs without anyone hand-writing them.
How much code must you usually write to get a basic Swagger UI with springdoc?
- Essentially none beyond adding the dependency
- A YAML file for every endpoint
- A separate documentation server
- A full custom controller
Answer: Essentially none beyond adding the dependency. Adding the springdoc starter dependency is enough to get a working /swagger-ui.html and /v3/api-docs; the annotations only enrich the auto-generated docs.