API Documentation with OpenAPI 3 and Swagger in Spring Boot

#openapi #swagger #springboot #restapi

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

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

Stop Guessing: Document Your APIs with OpenAPI 3 and Swagger in Spring Boot

Remember the last time you integrated with a new service or onboarded a junior developer? The frantic Slack messages, the endless Postman imports, the "just try this endpoint" advice. That chaos is a sign of poor API documentation. Outdated Word documents or READMEs just don't cut it. Modern backend development demands living, breathing documentation that evolves with your code. This is where OpenAPI Swagger Spring Boot shines, transforming your API contracts into interactive, developer-friendly guides. Let's make that pain a thing of the past.

Getting Started with springdoc-openapi-ui

Integrating OpenAPI 3 into your Spring Boot application is incredibly straightforward, thanks to the springdoc-openapi-ui library. This library automatically generates OpenAPI 3 documentation from your Spring Boot application and provides a fully functional Swagger UI to interact with it. All it takes is a single dependency in your pom.xml. No complex configuration required to get a basic setup running. Once added, launch your application, and navigate to /swagger-ui.html to see your API endpoints beautifully laid out.

<!-- pom.xml -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version> <!-- Use the latest stable version -->
</dependency>

This minimal setup is perfect for quick starts. In production, springdoc adds very little overhead. We've seen it perform without issue even on heavily trafficked services handling thousands of requests per second. The initial startup time increase is negligible, and memory footprint remains low, making it a reliable choice for critical applications where resource efficiency is paramount. You get interactive documentation without sacrificing performance.

Annotate Your Way to Clarity

While springdoc-openapi-ui provides basic documentation out of the box, you'll want to add more detail to make your API truly understandable. OpenAPI 3 annotations allow you to define summaries, descriptions, request bodies, response schemas, and more, directly within your controller code. This keeps documentation close to the source, reducing the chances of it becoming stale. @Operation and @ApiResponse are your main tools here, providing context for each endpoint and its possible outcomes.

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

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

    @Operation(summary = "Get a product by ID", description = "Retrieves details of a single product based on its unique identifier.")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Product found successfully"),
        @ApiResponse(responseCode = "404", description = "Product not found")
    })
    @GetMapping("/{id}")
    public Product getProductById(@PathVariable Long id) {
        // ... implementation
        return new Product(id, "Example Product", 29.99);
    }
}

Using these annotations forces you to think about your API contract upfront, improving design. In a production environment, this rigor helps us maintain consistency across microservices and reduce integration bugs. When new teams consume an API, a clear @ApiResponse for a 400 Bad Request or a 401 Unauthorized response saves them hours of debugging. This pre-emptive clarity directly contributes to faster development cycles and fewer post-release issues.

Customizing API Info and Swagger UI

Beyond individual endpoint documentation, you can define global API information like title, version, and contact details. This is crucial for branding your API and providing developers with essential context. You can achieve this using the @OpenAPIDefinition annotation on your main application class or through application.yml properties. The springdoc library also allows for fine-grained control over the Swagger UI itself, enabling you to customize paths, security schemes, and even hide certain endpoints in production.

// Main application class
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.servers.Server;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@OpenAPIDefinition(
    info = @Info(
        title = "Product Service API",
        version = "1.0",
        description = "API for managing products in the catalog.",
        contact = @Contact(name = "Shubham Bhati", email = "shubham.bhati@example.com")
    ),
    servers = {
        @Server(url = "http://localhost:8080", description = "Local Development Server"),
        @Server(url = "https://api.example.com", description = "Production Server")
    }
)
@SpringBootApplication
public class ProductApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProductApplication.class, args);
    }
}

In production setups, we often configure springdoc to hide /swagger-ui.html on public-facing instances, exposing it only within our internal network or for specific roles. This prevents accidental exposure of internal endpoints or sensitive information. Customizing the springdoc.swagger-ui.path property allows you to move the UI to a less discoverable URL, providing an additional layer of basic security. This careful control ensures that while documentation is easy to access for developers, it remains secure where it matters.

Common Pitfalls

Missing springdoc-openapi-ui dependency: The most common oversight. Without it, /swagger-ui.html will be a 404.
Stale documentation: Forgetting to regenerate docs after code changes, especially if not using a build pipeline that ensures this. Manual annotation updates are key.
Exposing sensitive endpoints: Ensure you don't expose /actuator endpoints or other internal APIs in your public OpenAPI documentation. Use @Hidden or springdoc properties to control visibility.
Over-documenting trivial getters/setters: Focus on the "what" and "why" of your API, not every internal field. Keep descriptions concise and to the point.

Conclusion

OpenAPI 3 and Swagger UI with Spring Boot are powerful tools for any backend developer. They eliminate communication friction, standardize API contracts, and significantly improve developer experience. By embracing springdoc-openapi-ui and thoughtful annotation, you transform your documentation from a neglected chore into an interactive, living asset. Make API documentation an integral part of your development workflow, not an afterthought. Your future self, and your team, will thank you.

DEV Community