Swagger Integration for API Documentation [Java Spring Boot Mastery Series – Part 9]

Swagger helps developers explore and test REST APIs directly from a browser. Spring Boot integrates Swagger through the Springfox or springdoc–openapi libraries.

🧰 1. Add Swagger Dependency (Spring Boot 3+ with springdoc-openapi)

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

Description:

• This dependency auto-configures OpenAPI 3 documentation and provides a Swagger UI at runtime.

⚙️ 2. Access Swagger UI

Once you start your Spring Boot app, navigate to:

http://localhost:8080/swagger-ui.html

You’ll see a user-friendly UI with all available endpoints and their request/response models.

🧾 3. Add API Metadata (Optional but Recommended)

Customize your OpenAPI docs using @OpenAPIDefinition:

@OpenAPIDefinition(
    info = @Info(
        title = "Product API",
        version = "1.0",
        description = "API documentation for managing products"
    )
)
@SpringBootApplication
public class MyApplication {}

🛡️ 4. Annotate Controllers and Models

Swagger automatically documents your REST controllers and model classes:

@RestController
@RequestMapping("/products")
public class ProductController {

    @Operation(summary = "Get all products")
    @GetMapping
    public List<Product> getAll() {
        return repository.findAll();
    }

    @Operation(summary = "Get product by ID")
    @GetMapping("/{id}")
    public ResponseEntity<Product> getById(@PathVariable Long id) {
        return repository.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }
}

📬 5. Postman Collection (Optional)

You can export and share Postman collections:

1. Open Swagger UI
2. Use the built-in “Export to Postman” options (or manually test and export from Postman)

➡️ Next Up: Part 10 – Security with Spring Boot (Basic Auth, JWT, OAuth2)