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.

Before You Start

You should have built REST controllers and DTOs and applied your database migrations with Flyway . Comfort with @RestController and @GetMapping is assumed.

What You'll Learn

The Big Idea — A Catalogue That Writes Itself

💡 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.

1️⃣ Add the Dependency, Get Docs for Free

Add the springdoc starter and restart. You immediately get /swagger-ui.html and /v3/api-docs — no extra code required.

2️⃣ Enrich Endpoints with @Operation, @ApiResponse, @Tag

springdoc infers paths and parameters automatically; these annotations add summaries, response details and grouping so the docs read clearly.

3️⃣ Documenting DTOs with @Schema

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.

4️⃣ The Machine-Readable Spec: /v3/api-docs

Swagger UI is just a viewer over this JSON. Tools consume /v3/api-docs directly to generate clients, mocks and contract tests.

5️⃣ The Idea, Concretely

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.

🧠 Quick Recall

Answer: at /v3/api-docs — the machine-readable description tools consume.

Answer: @Schema , with a description and example.

Common Errors

• ❌ Looking for docs at /swagger.json . Wrong path. Fix: the JSON is at /v3/api-docs .
• ❌ Importing the wrong @Schema. There are several. Fix: use io.swagger.v3.oas.annotations.media.Schema .
• ❌ Using the old springfox library. Unmaintained for Spring Boot 3. Fix: use springdoc-openapi .
• ❌ Expecting annotations to define endpoints. They only enrich. Fix: endpoints come from your @RestController mappings.
• ❌ Forgetting the -ui starter. No Swagger UI appears. Fix: use the ...-starter-webmvc-ui artifact.

Pro Tips

• 💡 Start with zero annotations — you already get usable docs; add detail where it helps.
• 💡 Always give realistic example values in @Schema so the UI and clients show sensible data.
• 💡 Document error responses with @ApiResponse for 400/404/500, not just the happy path.
• 💡 Treat /v3/api-docs as a contract — feed it to client generators and contract tests.

📋 Quick Reference

Item

Value / annotation

Note

UI

/swagger-ui.html

interactive docs

spec

/v3/api-docs

OpenAPI 3 JSON

endpoint

@Operation

summary/description

outcome

@ApiResponse

a status + meaning

group

@Tag

cluster endpoints

model

@Schema

field docs/example

📚 Resources / Keep Learning

• 📘 springdoc-openapi — Official Documentation
• 📗 OpenAPI 3 Specification
• 📗 Swagger UI — what it renders

❓ Frequently Asked Questions

🎉 Lesson Complete!

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

Continue this course

• Previous: Database Migrations with Flyway
• Next: Async & Scheduled Tasks