API Documentation with OpenAPI 3 and Swagger in Spring Boot

#openapi #swagger #springboot #restapi

Published 2026-08-11 by Shubham Bhati — Backend Engineer (Java 17, Spring Boot, Microservices).

Master API Documentation with OpenAPI 3 and Swagger in Spring Boot

By Shubham Bhati, Backend Engineer (Java 17, Spring Boot, Microservices)

Ever struggled integrating with an internal API, only to find the "documentation" was a Slack message from six months ago, or worse, "just read the code"? That pain point, dear developer, is real. Undocumented or poorly documented APIs lead to wasted time, broken integrations, and frustrating onboarding. For Java and Spring Boot backend teams, this isn't just an inconvenience; it's a productivity killer. Fortunately, modern tooling like OpenAPI Swagger Spring Boot offers a powerful, standardized solution to generate and maintain clear API documentation automatically. Let's make that undocumented API a relic of the past.

Kickstarting with Springdoc-OpenAPI

To get started, we'll use springdoc-openapi, a library that integrates OpenAPI 3 specifications with Spring Boot applications. It automatically generates API documentation from your Spring annotations and configurations. This means less manual effort and more up-to-date docs. Add the following dependency to your pom.xml:

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

This single dependency pulls in everything you need, including the Swagger UI. Once added, restart your Spring Boot application, and you'll find your basic API documentation accessible at /swagger-ui.html (or /v3/api-docs for the raw JSON/YAML spec). A well-documented API reduces the cognitive load for developers consuming your service, whether they're in your team or another. This clarity translates directly into faster development cycles and fewer integration bugs, significantly boosting overall team velocity. Don't underestimate the power of a clear API contract.

Enriching Your API with OpenAPI Annotations

While springdoc-openapi does a great job generating basic documentation, you can provide much richer detail using OpenAPI annotations directly in your Spring controllers. These annotations allow you to describe operations, parameters, responses, and even group related endpoints using tags. This level of detail makes your Swagger UI incredibly useful for consumers, providing clear examples and explanations.

Here’s an example of how you might annotate a simple REST endpoint:

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

@Tag(name = "User Management", description = "Operations related to users")
@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "Get a user by ID", description = "Retrieves details of a specific user.")
    @ApiResponse(responseCode = "200", description = "User found successfully")
    @ApiResponse(responseCode = "404", description = "User not found")
    @GetMapping("/{id}")
    public User getUserById(@Parameter(description = "ID of the user to retrieve") @PathVariable Long id) {
        // ... business logic ...
        return new User(id, "Shubham Bhati");
    }
}

Annotations like @Operation describe the purpose of an endpoint, @ApiResponse details potential responses, and @Tag helps categorize your API. Consistent application of these annotations is crucial for maintainability; treat them as an integral part of your API contract and include them in code reviews to ensure clarity and accuracy.

Customizing Swagger UI and Adding Security

The default Swagger UI is functional, but you'll often want to customize its appearance or secure access. springdoc-openapi provides properties in application.yml to achieve this. You can change the title, description, version, and even customize the path to the Swagger UI. Crucially, you can also configure security schemes like Bearer Token authentication, making your documentation reflect how clients should interact with your protected endpoints.

springdoc:
  swagger-ui:
    path: /api-docs/swagger-ui.html # Custom path for Swagger UI
    disable-swagger-default-url: true # Hide default url
    operationsSorter: alpha # Sort operations alphabetically
    tagsSorter: alpha # Sort tags alphabetically
  api-docs:
    path: /api-docs # Custom path for OpenAPI spec (JSON/YAML)
  info:
    title: My Service API
    version: 1.0.0
    description: Documentation for My Service's RESTful API
  # Security configuration (for Bearer Token example)
  security:
    - name: BearerAuth
      type: http
      scheme: bearer
      bearerFormat: JWT

Production Note: Always disable or restrict access to /swagger-ui.html and /v3/api-docs in production environments. Exposing your full API documentation publicly can be a significant security risk, providing attackers with detailed knowledge of your endpoints and data models. Consider an API Gateway or specific security rules to protect these endpoints.

Common Pitfalls

Forgetting to disable or secure in Production: Leaving Swagger UI accessible in production is a major security vulnerability. Always disable it or put it behind strong authentication and authorization.
Outdated Documentation: If the code changes but the annotations don't, your documentation becomes misleading. Make documentation updates part of your definition of done for every API change.
Over-annotating or Under-annotating: Find a balance. Don't document every trivial detail, but ensure all critical parameters, responses and potential error codes are clearly described.
Ignoring API Versioning: When your API evolves, your documentation should reflect the different versions. Consider how you'll handle v1, v2 of your API in your documentation strategy.

Conclusion

Implementing OpenAPI 3 and Swagger in your Spring Boot applications transforms the developer experience. It provides clarity, reduces onboarding time for new team members and streamlines integration with other services. By automating your API documentation with springdoc-openapi, you ensure consistency and accuracy, freeing your team to focus on building features rather than deciphering undocumented endpoints. Embrace this powerful combination and bring order to your API landscape.