LearnAI ToolsCareerPractice BuildsPlayContact
Lesson 2316 min read

API Documentation Dependencies (OpenAPI/Swagger)

Learn how to auto-generate interactive API documentation for a Spring Boot application using springdoc-openapi.

Introduction

Hand-written API documentation goes stale the moment an endpoint changes. springdoc-openapi solves this by generating an OpenAPI specification — and a browsable Swagger UI — directly from your controllers, DTOs, and annotations, so the docs are always in sync with the actual code.

What You Will Learn
  • What problem springdoc-openapi-starter-webmvc-ui solves.
  • How to get interactive API docs with zero configuration.
  • How to customize generated docs with @Operation and @Schema annotations.

Why You Need This Dependency

Use case: any REST API consumed by a frontend team, mobile team, or external partners benefits from live, interactive documentation where consumers can read request/response shapes and even try requests directly from the browser — without you maintaining a separate document by hand.

Adding the Dependency

pom.xml
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>
Not a Spring Boot Starter

springdoc-openapi is a third-party library, not an official spring-boot-starter, so unlike most dependencies in this course it is not managed by spring-boot-starter-parent — you do need to specify its version explicitly, and check for the latest release when you add it.

Zero-Config Documentation

With just the dependency on the classpath and no further configuration, springdoc-openapi scans your @RestController classes and exposes two endpoints automatically.

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


    @GetMapping("/{id}")
    public Product getProduct(@PathVariable Long id) {
        return new Product(id, "Wireless Mouse", 799.0);
    }


    @PostMapping
    public Product createProduct(@RequestBody Product product) {
        return product;
    }
}
EndpointPurpose
/v3/api-docsRaw OpenAPI 3.0 specification in JSON
/swagger-ui.htmlInteractive, browsable API documentation UI
Result

Click Run to see what this code prints.

Customizing with Annotations

Default generated docs are functional but generic. Use @Operation to describe an endpoint in human terms, and @Schema to document individual fields on your DTOs.

ProductController.java
@Operation(
        summary = "Get a product by ID",
        description = "Returns full product details, including price, for a given product ID."
)
@GetMapping("/{id}")
public Product getProduct(@PathVariable Long id) {
    return new Product(id, "Wireless Mouse", 799.0);
}
Product.java
public record Product(


        @Schema(description = "Unique identifier of the product", example = "101")
        Long id,


        @Schema(description = "Display name shown to customers", example = "Wireless Mouse")
        String name,


        @Schema(description = "Price in INR", example = "799.00")
        double price
) {}
Result

Click Run to see what this code prints.

Common Mistakes

Avoid These Mistakes
  • Leaving springdoc-openapi enabled with full Swagger UI exposed on a production endpoint without any access restriction.
  • Forgetting to pin an explicit version, since this dependency is not managed by spring-boot-starter-parent.
  • Documenting only the happy path and skipping error responses, which real API consumers need just as much.
  • Letting DTOs go undocumented, leaving Swagger UI showing bare field names with no context.

Best Practices

  • Restrict or disable Swagger UI in production environments, or put it behind authentication.
  • Use @Operation and @ApiResponse together to document both success and error responses.
  • Group related endpoints with @Tag for a cleaner Swagger UI navigation experience.
  • Treat the generated OpenAPI spec as a contract frontend and partner teams can code against.

Frequently Asked Questions

No. Springfox is an older, now largely unmaintained library. springdoc-openapi is the modern, actively maintained successor and supports OpenAPI 3.

The impact is negligible for typical applications — it scans annotations at startup and serves the generated spec/UI on dedicated endpoints.

Yes, the JSON returned from /v3/api-docs is a standard OpenAPI document that can be imported directly into Postman, Insomnia, or code generators.

Summary

springdoc-openapi-starter-webmvc-ui turns your existing controllers and DTOs into live, interactive API documentation with zero required configuration, and @Operation/@Schema let you refine that documentation with almost no extra effort.

Lesson 23 Completed
  • You understand why auto-generated API docs beat hand-written ones.
  • You got Swagger UI running with zero configuration.
  • You customized generated docs with @Operation and @Schema.
Next Lesson →

Scheduling & Batch Processing Dependencies