More›Extra· 35 min read

API Docs with Swagger / OpenAPI

Add one dependency and get a live, interactive documentation page for your whole API — generated automatically from your controllers.

What you will learn

Add springdoc-openapi to auto-generate API docs
Open the interactive Swagger UI
Describe endpoints with annotations

Why APIs need documentation

When someone — a front-end developer, a teammate, an employer — uses your API, they need to know what endpoints exist, what each expects, and what it returns. Writing that by hand is tedious and goes stale the moment you change the code. The professional solution generates it automatically from your code.

OpenAPI is the industry standard format for describing a REST API. Swagger UI is a web page that reads that description and lets anyone try the endpoints right in the browser. In Spring you get both from one library: springdoc-openapi.

Step 1: add the dependency

Add springdoc to pom.xml — that is almost the whole setup:

pom.xml: springdoc-openapi (Swagger UI included)

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

Note: Output: (No output — this adds OpenAPI doc generation plus the Swagger UI page. No code changes are required to get started.)

Step 2: open the docs

Restart the app and open the Swagger UI in your browser. springdoc scanned your controllers and built the whole page for you:

The two URLs springdoc gives you

# the interactive documentation page:
http://localhost:8080/swagger-ui.html

# the raw machine-readable description:
http://localhost:8080/v3/api-docs

Note: Output: Opening /swagger-ui.html shows a page listing every endpoint, grouped by controller: GET /products List products GET /products/{id} Get one product POST /products Create a product PUT /products/{id} Update a product DELETE /products/{id} Delete a product Each row expands so you can fill in parameters and click "Try it out" to call the real endpoint and see the live response — no Postman needed.

Step 3: describe endpoints more clearly (optional)

The auto-generated docs are already useful. To make them friendlier, add a few annotations that turn into human-readable descriptions:

Annotations that enrich the generated docs

@Operation(summary = "Get one product by its id")
@ApiResponse(responseCode = "200", description = "Product found")
@ApiResponse(responseCode = "404", description = "No product with that id")
@GetMapping("/products/{id}")
public ProductDto one(@PathVariable Long id) {
    return service.getProduct(id);
}

Note: Output: In Swagger UI this endpoint now shows the summary "Get one product by its id" and lists its two possible responses (200 and 404) with descriptions. The annotations are documentation only — they do not change how the endpoint behaves.

Tip: Swagger UI is a fantastic way to demo your project to an employer: open the page, click “Try it out”, and call live endpoints in front of them — no extra tools, no setup on their side. Add the link to your project’s README.

Watch out: Swagger UI exposes a full map of your API, so in production decide whether it should be public. It is common to leave it on for internal/staging APIs but disable it (or put it behind login) for public production services.

Q. What does adding springdoc-openapi give you?

Answer: springdoc-openapi scans your controllers and generates an OpenAPI description plus an interactive Swagger UI page, so anyone can read your endpoints and try them live in the browser.

✍️ Practice

Add springdoc-openapi and open /swagger-ui.html for your CRUD API.
Add an @Operation(summary = ...) to two endpoints and see the text appear in Swagger UI.

🏠 Homework

Add Swagger/OpenAPI to your Task API, describe each endpoint with a short @Operation summary, and use “Try it out” to create and list a task from the docs page.