[MM’s] Boot Notes — Documenting Spring Boot APIs: Springdoc OpenAPI Takes the Lead

The fastest way to onboard new engineers and integration partners to your API.

You’ve shipped a REST API. A developer tries to integrate with it.

Three sprints later, your README still says “TODO: document the API.”
Your Postman collection is outdated. The last time someone ran Swagger UI, it was using SpringFox in 2020 — before Spring Boot 4 even existed.

Manual documentation doesn’t scale. It diverges from code the moment you merge. That’s why Springdoc OpenAPI has become the de facto way to generate up-to-date, interactive API documentation for modern Spring Boot projects.

⚡ TL;DR (Quick Recap)

SpringFox is obsolete — no updates since 2020; incompatible with Spring Boot 3.x+
Springdoc OpenAPI supports Spring Boot 3.x and 4.x, Java 21+, and OpenAPI 3.1
Zero config: Works out-of-the-box with springdoc-openapi-starter-webmvc-ui
Interactive UI: Choose between Swagger UI and the new Scalar UI
Production-safe: Disable docs with simple properties
BOM and plugins: Easy dependency management and build-time doc generation

Why API Documentation Deserves Better

Spring Boot 4.0 brings native API versioning, structured observability and virtual threads. But none of that matters if your consumers can’t understand your API.

Frontend teams waste hours guessing payload formats
QA teams test blind
Integration partners flood Slack with the same “what’s the response?” questions
New engineers need days to onboard

Good documentation turns an API into a self-service product. The best way to achieve that is by generating docs directly from your source code.

That’s where Springdoc OpenAPI shines — it reads your Spring Boot configuration, annotations and class structure, then automatically produces machine-readable OpenAPI specs and human-friendly interactive docs.

From SpringFox to Springdoc: The Shift That Had to Happen

For years, SpringFox Swagger was the default documentation tool in the Spring world. But in 2025, it’s effectively abandoned.

The SpringFox Problem

No release since July 2020 (over five years dormant)
Supports Swagger 2.0 only (OpenAPI 2.0)
Breaks on Spring Boot 3+ due to javax → jakarta migration
No Java records or virtual thread support
Reflection-heavy, incompatible with GraalVM native images
Requires manual Docket configuration

Why Springdoc OpenAPI Wins

Active development — latest version v2.8.14 (2025)
Native OpenAPI 3.1 support
Full Spring Boot 3.x and 4.0 and Java 21+ compatibility
Auto-configuration via Spring Boot starters
Supports records, sealed classes, and pattern matching
GraalVM AOT friendly
Seamless integration with Bean Validation and Jakarta EE 9+
New Scalar UI for cleaner, modern API exploration

In short, Springdoc OpenAPI is the only production-grade option for documenting modern Spring Boot APIs.

Implementation Guide: From Zero to Documented in 5 Steps

Step 1: Add Dependencies

Centralize versioning in your parent POM using the new BOM:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-bom</artifactId>
      <version>2.8.14</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Then add the WebMVC starter in your modules:

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

By default, your app now exposes:

/v3/api-docs — OpenAPI spec (JSON/YAML)
/swagger-ui.html — Swagger UI
/scalar — Scalar UI (new in v2.8.x)

Step 2: Add API Metadata

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI apiInfo() {
        return new OpenAPI()
            .info(new Info()
                .title("HTTP Client Demo API")
                .version("1.0.0")
                .description("Demonstrates HTTP client approaches in Spring Boot 4.0")
                .license(new License()
                    .name("Apache 2.0")
                    .url("https://www.apache.org/licenses/LICENSE-2.0")));
    }
}

This information appears in both the OpenAPI spec and Swagger UI header.

Step 3: Annotate Your Controllers

@RestController
@RequestMapping("/api/demos")
@Tag(name = "Demos", description = "CRUD operations for demo entities")
public class DemoApi {
    private final DemoService service;
    public DemoApi(DemoService service) {
        this.service = service;
    }
    @Operation(summary = "Create a new demo")
    @ApiResponse(responseCode = "201", description = "Demo created")
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Demo create(@Valid @RequestBody Demo demo) {
        return service.createDemo(demo);
    }
    @Operation(summary = "Get all demos")
    @GetMapping
    public List<Demo> getAll() {
        return service.getAllDemos();
    }
}

Springdoc scans these annotations automatically — no configuration required.

Step 4: Annotate DTOs and Use Records

@Schema(description = "Demo entity for HTTP client operations")
public record Demo(
    @Schema(description = "Demo ID", example = "demo-123")
    String id,
@NotBlank @Schema(description = "Demo name", example = "Sample Demo")
    String name
) {}

Validation annotations like @NotBlank or @Size appear automatically in Swagger UI examples.

Step 5: Document API Versioning (Spring Boot)

Spring Boot new version-based routing integrates seamlessly:

@RestController
@RequestMapping("/api/products")
@Tag(name = "Products")
public class ProductApi {
    @Operation(summary = "Get product v1.0")
    @GetMapping(path = "/{id}", version = "1.0")
    public Product getV1(@PathVariable String id) {
        return new Product(id, "Coffee Maker", 49.99);
    }
    @Operation(summary = "Get product v2.0")
    @GetMapping(path = "/{id}", version = "2.0")
    public ProductV2 getV2(@PathVariable String id) {
        return new ProductV2(id, "Coffee Maker", 4999, "USD");
    }
}

Both versions appear clearly in the generated documentation.

The Developer Experience Transformation

Before Springdoc OpenAPI

API contracts lived in tribal knowledge
Documentation scattered across Notion or Confluence
Integration tests served as “documentation”
Onboarding new devs took days

After Springdoc OpenAPI

Instant interactive docs at /swagger-ui.html or /scalar
Example payloads auto-generated
“Try it out” testing built-in
/v3/api-docs serves as source of truth for SDK generation
Integration with tools like openapi-generator or stoplight

Going Beyond Basics

Actuator Integration

Expose documentation endpoints on a management port:

springdoc.use-management-port=true
management.endpoints.web.exposure.include=openapi,swagger-ui,scalar

Docs become available at:

/actuator/openapi
/actuator/swagger-ui
/actuator/scalar

Scalar UI

Prefer a modern API client experience? Scalar UI (bundled with v2.8.x) provides a polished, single-page interface with a built-in REST client.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-scalar</artifactId>
</dependency>

Then open http://localhost:8080/scalar.

Build-Time Documentation Generation

For CI/CD environments, Springdoc can export your OpenAPI spec at build time.

Maven plugin:

<plugin>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-maven-plugin</artifactId>
  <version>1.5</version>
  <executions>
    <execution>
      <goals><goal>generate</goal></goals>
    </execution>
  </executions>
</plugin>

Production Deployment

Swagger and Scalar UIs expose internal API structure — if you want, you can disable them in production:

springdoc.api-docs.enabled=false
springdoc.swagger-ui.enabled=false
springdoc.scalar.enabled=false

You can still generate build-time specs safely for API gateways or external consumers.

Migration from SpringFox

Migration is straightforward:

Remove all springfox-* dependencies
Add the Springdoc starter
Replace annotations:

@Api → @Tag
@ApiOperation → @Operation
@ApiParam → @Parameter
@ApiModel → @Schema

Update imports:
io.swagger.annotations → io.swagger.v3.oas.annotations

Done — your new docs appear instantly at /swagger-ui.html.

Final Takeaways

Springdoc OpenAPI is now the official path forward for documenting Spring Boot APIs.
It supports the latest Spring Boot 4, Java 21+, OpenAPI 3.1, and GraalVM environments.
The Scalar UI, BOM support, and Actuator integration make it even more production-friendly.
Migration from SpringFox is fast — and mandatory for modern projects
Stop maintaining stale Postman collections. Let your code document itself.

You can find all the code on GitHub.

Originally posted on marconak-matej.medium.com.

[MM’s] Boot Notes — Documenting Spring Boot APIs: Springdoc OpenAPI Takes the Lead