API Documentation with OpenAPI 3 and Swagger in Spring Boot

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

End API Documentation Headaches with OpenAPI 3 and Swagger in Spring Boot

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

Ever tried integrating with an undocumented API? The endless guesswork, the broken contracts, the frustrating back-and-forth communication – it's a productivity killer. In the world of microservices, clear API documentation isn't just a nice-to-have, it's a necessity for smooth developer experience and reliable integrations. This is where OpenAPI 3 and Swagger in Spring Boot step in. By leveraging the springdoc-openapi library, we can effortlessly generate and visualize interactive API documentation, transforming client onboarding and preventing countless integration issues. Let's make API documentation a source of truth, not a source of pain.

Quick Setup: Integrating springdoc-openapi

Getting started with OpenAPI 3 and Swagger UI in your Spring Boot application is straightforward. The springdoc-openapi library automates much of the heavy lifting, introspecting your Spring controllers and generating an OpenAPI specification. You only need to add a single dependency to your pom.xml. This minimal setup quickly provides a /v3/api-docs endpoint for your OpenAPI JSON/YAML specification and a /swagger-ui.html endpoint for the interactive Swagger UI.

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version> <!-- Use the latest version -->
</dependency>

That's it for the basic setup. Once your application starts, navigate to http://localhost:8080/swagger-ui.html (or your application's base URL) to see your API documentation. The springdoc library itself is lightweight, adding negligible memory footprint or startup time overhead. In production environments, while the generated spec is crucial, you might consider excluding the springdoc-openapi-ui dependency to avoid exposing the interactive UI publicly, especially if your API is internal or requires strict access controls. Keep the spec generation, hide the UI.

Documenting Your Controllers with Annotations

While springdoc-openapi can generate basic documentation from your controller and model classes, enriching it with OpenAPI-specific annotations provides a far more descriptive and useful spec. Annotations like @Operation, @ApiResponse, and @Parameter from io.swagger.v3.oas.annotations allow you to add summaries, descriptions, response codes, examples and parameter details directly within your code. This "code-first" approach keeps documentation close to the implementation, making it easier to maintain.

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.*;

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

    @Operation(summary = "Get a product by ID", description = "Retrieves details of a single product based on its unique identifier.")
    @ApiResponse(responseCode = "200", description = "Product found", 
                 content = @Content(schema = @Schema(implementation = Product.class)))
    @ApiResponse(responseCode = "404", description = "Product not found")
    @GetMapping("/{id}")
    public Product getProductById(
            @Parameter(description = "ID of the product to retrieve", example = "UUID-123")
            @PathVariable String id) {
        // ... implementation
        return new Product(id, "Example Product", 99.99);
    }
}

These annotations provide critical context for consumers, defining expected inputs, potential outputs and error conditions. This detailed metadata is invaluable for client-side code generation tools, preventing common integration errors that often manifest as P99 latency spikes due to invalid requests. It ensures that consumers understand the API contract without needing to consult external documents, leading to faster development cycles.

Customizing Your OpenAPI Specification and Swagger UI

Beyond basic generation, springdoc-openapi offers extensive customization options via application.yml or a Java configuration bean. You can define global API information like title, description, version and even security schemes directly in your application.yml. This standardization is key when managing multiple microservices, ensuring a consistent API catalog.

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  info:
    title: My Product Service API
    description: Documentation for the Product Management Service.
    version: 1.0.0
    contact:
      name: Shubham Bhati
      email: [e-mail]

For more advanced configurations, such as defining global security requirements or custom groups of APIs, you can create a OpenApi bean. This allows you to add SecuritySchemes for API keys, OAuth2 or JWT bearer tokens. A well-defined security scheme in your OpenAPI spec guides clients on how to authenticate, drastically reducing integration friction. Ensuring all microservices provide a consistent and detailed spec prevents integration issues that often show up as P99 latency spikes because of repeated failed authorization attempts.

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.Components;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Product Service API").version("1.0.0").description("Product Management API"))
                .components(new Components()
                        .addSecuritySchemes("bearerAuth",
                                new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
    }
}

Common Pitfalls

• Documentation Drift: Forgetting to update @Operation or @Parameter annotations when API contracts change. This leads to misleading documentation and broken client integrations.
• Exposing Swagger UI in Production: While the OpenAPI spec is valuable, the interactive Swagger UI should often be restricted or disabled in production for public-facing APIs to prevent information leakage or unauthorized access.
• Over-Documenting Trivial Endpoints: Focus on documenting complex or critical endpoints. Not every internal health check needs elaborate descriptions.
• Ignoring Request/Response Examples: Without concrete examples in @Schema or @Content, understanding the data structure can still be a challenge for consumers.
• Lack of CI/CD Integration: Not integrating OpenAPI spec validation or generation into your CI/CD pipeline means documentation discrepancies can slip into production.

Conclusion

Effective API documentation with OpenAPI 3 and Swagger in Spring Boot is more than a formality; it's a cornerstone of productive development and stable systems. By integrating springdoc-openapi and leveraging its powerful annotations and configuration options, you create a living, breathing source of truth for your API. This clarity reduces developer onboarding time, minimizes integration errors and ultimately fosters a more collaborative development environment. Document your APIs well, and watch your team's efficiency soar.

---

Further Reading

• Spring Boot Official Documentation
• Baeldung — Java & Spring Tutorials
• Oracle Java Documentation

---

Written by **Shubham Bhati* — Backend Engineer at AlignBits LLC, specializing in Java 17, Spring Boot, microservices, and AI integration. Connect on LinkedIn, GitHub, or read more at shubh2-0.github.io.*