SpringDoc OpenAPI Integration

Introduction

API consumers need accurate OpenAPI docs—paths, parameters, schemas, and try-it-out UI. SpringDoc OpenAPI generates specs from your Spring MVC controllers at runtime in Boot 3. This chapter adds Swagger UI, groups APIs, secures docs in production, and keeps annotations maintainable.

Prerequisites

Add Dependency

xml

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

Use current 2.x line compatible with Spring Boot 3 / Jakarta.

Default URLs

Start app and open:

URL	Content
`http://localhost:8080/swagger-ui.html`	Swagger UI (redirects)
`http://localhost:8080/swagger-ui/index.html`	UI
`http://localhost:8080/v3/api-docs`	OpenAPI JSON

No extra @EnableSwagger2—SpringDoc auto-registers.

Document a Controller

java

Records and validation annotations appear in schema automatically.

Global API Info

java

Group APIs

yaml

springdoc:
  group-configs:
    - group: public
      paths-to-match: /api/**
    - group: admin
      paths-to-match: /admin/**

Access grouped docs: /v3/api-docs/public, UI group dropdown.

Production Strategy

Hide or protect docs in prod:

yaml

springdoc:
  api-docs:
    enabled: ${SWAGGER_ENABLED:false}
  swagger-ui:
    enabled: ${SWAGGER_ENABLED:false}

Set SWAGGER_ENABLED=true only in staging—or require authentication (integrate with Spring Security chapter).

Warning

Do Not Expose Internal Admin APIs

Use @Hidden on internal controllers or path filters to exclude from public spec.

java

import io.swagger.v3.oas.annotations.Hidden;
 
@Hidden
@RestController
@RequestMapping("/internal/health-detail")
public class InternalController { }

Keep Docs in Sync

Practice	Why
Annotate DTO fields with `@Schema(description = "...")`	Clear consumer docs
Document error responses	`@ApiResponse(responseCode = "404", ...)`
Regenerate client SDK from `/v3/api-docs` in CI	Single source of truth

Avoid maintaining separate Word spec that drifts from code.

FAQ

springfox vs springdoc?

springfox does not support Boot 3—use springdoc.

UI 404?

Check dependency artifact springdoc-openapi-starter-webmvc-ui and context path server.servlet.context-path.

Bearer JWT in Try it out?

Configure OpenAPI Components security scheme—after Security chapter wire SecurityRequirement.

Large spec slow?

Limit scanned packages or use groups.

Export YAML?

/v3/api-docs.yaml when springdoc.api-docs.path configured.

Kotlin controllers?

SpringDoc supports Kotlin with same annotations.