Springdoc-openapi integration with Spring Boot is surprisingly simple, but the complexity arises when you realize it’s not just about generating a spec, but about actively shaping how your API is understood by the world.
Let’s see it in action. Imagine a basic Spring Boot application with a REST controller:
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
@RestController
@RequestMapping("/api/v1/users")
public class UserController {
private final Map<String, User> users = new ConcurrentHashMap<>();
@GetMapping("/{id}")
public User getUser(@PathVariable String id) {
return users.get(id);
}
@PostMapping
public User createUser(@RequestBody User user) {
users.put(user.getId(), user);
return user;
}
// Assume User class exists with id, name, email
public static class User {
private String id;
private String name;
private String email;
// Getters and setters
public String getId() { return id; }
public void setId(String id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public String getEmail() { return email; }
public void setEmail(String email) { this.email = email; }
}
}
To integrate springdoc-openapi, you only need to add the dependency to your pom.xml:
<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. No configuration classes, no explicit bean definitions. If you run your Spring Boot application and navigate to /swagger-ui.html (or /v3/api-docs for the raw OpenAPI spec), you’ll immediately see your API documented. The springdoc-openapi library automatically scans your Spring Boot application, inspects your controllers, request mappings, request bodies, and response types, and generates an OpenAPI 3 specification.
The core problem springdoc-openapi solves is the disconnect between your live API implementation and its documentation. Traditionally, you’d have to manually write and maintain OpenAPI (Swagger) specifications, which is tedious and error-prone. springdoc-openapi bridges this gap by generating the spec directly from your code, ensuring your documentation is always in sync with your application’s behavior.
Internally, springdoc-openapi leverages Spring’s component scanning and reflection capabilities. It identifies classes annotated with @RestController, @Controller, and other relevant Spring annotations. For each controller, it then inspects methods annotated with HTTP method annotations (@GetMapping, @PostMapping, etc.). It analyzes method parameters, looking for @PathVariable, @RequestParam, @RequestBody, and their types, to define the API’s parameters and request bodies. Similarly, it examines the return types to define the API’s responses.
The primary lever you control is how you structure your Spring Boot application and the annotations you use. Well-defined DTOs (Data Transfer Objects) with appropriate Java Bean validation annotations (like @NotNull, @Size) directly translate into schema definitions with validation rules in your OpenAPI spec. For instance, if your User class had @NotNull private String name;, the generated OpenAPI spec would reflect that the name property is required.
You can customize the generated documentation extensively. For example, to add an API description and title, you can use springdoc.api-docs.title and springdoc.api-docs.description properties in your application.properties or application.yml.
springdoc.api-docs.title=My Awesome API
springdoc.api-docs.description=A demo API for user management
springdoc.api-docs.version=1.0.0
This provides a much richer and more informative documentation experience than just the raw API endpoints.
A common point of confusion is how to handle complex request/response structures or custom serialization. springdoc-openapi relies heavily on Jackson for JSON serialization. If you have custom Jackson serializers or deserializers, ensure they are correctly configured and that springdoc-openapi can infer the resulting schema. For example, if you use @JsonFormat on a field, it will be reflected in the schema’s format property.
When you have multiple Spring Boot applications or microservices, each needs its own springdoc-openapi dependency. The generated OpenAPI specs can then be aggregated by an API gateway or a separate documentation aggregator tool to provide a unified view of your entire system.
The next logical step is to explore how to secure your API documentation, which involves integrating Spring Security with springdoc-openapi.