Chapter 5.6☕ 14 min read

Swagger OpenAPI Documentation

Frontend devs love you when your APIs are documented. Swagger does it automatically.

01The Concept: API Contracts

The Paradise Restaurant Menu Card Analogy:

When you visit Paradise restaurant, you don’t walk into the kitchen to ask the chef what is cooking. You look at the Menu Card. The menu tells you the dish name, ingredients, and price.

Swagger is the Menu Card for your REST APIs. It scans your Spring Boot controllers, reads the @GetMapping and @PostMapping annotations, and builds a beautiful web page where frontend developers can view all your APIs and even test them live.

02Technical Explanation

OpenAPI 3: The modern industry standard for describing REST APIs.
springdoc-openapi: The library Spring Boot uses to generate OpenAPI docs. (Note: springfox is outdated and does not work with Spring Boot 3).
@Operation & @Parameter: Swagger annotations used to add human-readable descriptions to your endpoints.

03Full Working Code: Swagger UI Setup

<!-- pom.xml -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

# application.properties
# Change the default swagger path
springdoc.swagger-ui.path=/docs

04The Documented Controller

package com.devinhyderabad;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/books")
@Tag(name = "Book Management", description = "Endpoints to manage books")
public class BookController {

    @GetMapping("/{id}")
    @Operation(summary = "Get a book by ID", description = "Returns a single book matching the provided ID")
    public Book getBook(
            @Parameter(description = "ID of the book", required = true)
            @PathVariable Long id) {
        return new Book(id, "Sample Title", "Sample Author");
    }

    @PostMapping
    @Operation(summary = "Create a new book")
    public Book createBook(@RequestBody Book book) {
        return book;
    }
}

Start your app and go to http://localhost:8080/docs in your browser. You will see an interactive UI listing your endpoints!

05Why It Matters / Interview Note

Interview Question: “How do you document APIs in Spring Boot 3?”

Answer: “I use springdoc-openapi-starter-webmvc-ui. It scans the controllers and generates an OpenAPI 3 JSON spec. It also serves a Swagger UI where developers can visualize the endpoints and send test requests directly from the browser.”

Enterprise Note: In production, you often want to hide certain APIs (like internal admin endpoints) from the public Swagger page. You can do this by annotating those specific endpoints with @Hidden.

Key Takeaways

✅ springdoc-openapi auto-generates OpenAPI 3 documentation for Spring Boot 3
✅ Swagger UI provides an interactive page to view and test endpoints
✅ @Operation and @Parameter add human-readable descriptions
✅ Use @Hidden to exclude internal endpoints from production Swagger docs

PreviousEntity-DTO Mapping 📋 All Chapters Next ChapterSpring Boot with Angular CORS →