springdoc-openapi: runtime OpenAPI 3 generation for Spring Boot 4

The problem springdoc-openapi solves for Spring Boot teams

A Spring Boot application already declares its HTTP surface in code: controller classes, request mappings, method signatures, JSR-303 constraints on fields. None of that is an OpenAPI document. Before springdoc-openapi, teams either maintained a spec by hand and watched it drift from the controllers, or wired up a generator that read the code at build time. The README describes the library as automating generation by examining an application at runtime to infer API semantics from Spring configurations, class structure and annotations. That is the whole pitch: the description is derived from the running application, not from a separate artifact someone has to remember to update.

The audience is narrow and specific. You need a Spring Boot project, and for the current line you need Spring Boot 4. The README states support for OpenAPI 3, Spring Boot v4 with Java 17 and Jakarta EE 9, JSR-303 constraints (@NotNull, @Min, @Max, @Size), Swagger UI, OAuth 2 and GraalVM native images. If you are documenting a non-Spring service, or a Spring application whose routes are assembled dynamically at runtime from data rather than annotations, the inference has nothing stable to read and the value drops sharply.

One framing detail matters for trust. The README says plainly that this is a community-based project, not maintained by the Spring Framework Contributors (Pivotal). It is Apache-2.0, with a Tidelift security contact for vulnerability reports rather than a vendor support desk. Treat it as infrastructure you depend on deliberately, not as something the Spring team ships.

How the runtime scanning actually works

The mechanism is inspection at startup and at request time. Springdoc hooks into the Spring context, walks the handler mappings and the bean definitions, and builds an in-memory model of paths, operations, parameters, request bodies and responses. Swagger annotations, where present, are merged on top of what the inference produced. The README puts it as: the library automatically generates documentation in JSON/YAML and HTML formatted pages, and the generated documentation can be complemented using swagger-api annotations. Inference first, annotation overrides second.

From that model the library exposes three surfaces. The README gives the exact paths: the Swagger UI page at http://server:port/context-path/swagger-ui.html, the JSON description at http://server:port/context-path/v3/api-docs, and a YAML rendering at /v3/api-docs.yaml. The context path is whatever your application uses, so a service mounted under /api serves its spec at /api/v3/api-docs. That detail trips people up when they put a gateway or a management port in front of the app.

Architecture-wise the repository is split by web stack rather than by feature. The top level contains springdoc-openapi-starter-webmvc-ui, springdoc-openapi-starter-webmvc-api, springdoc-openapi-starter-webflux-ui and springdoc-openapi-starter-webflux-api, plus a BOM module and variants for scalar and MCP. That layout tells you the choice you make is which starter matches your stack, and the README's getting-started section targets the Web MVC case. WebFlux is supported, but the README's own note is that the webflux support it documents is for annotated controllers, which is a real boundary: functional endpoint styles are demonstrated separately in the demo applications rather than described in the same paragraph.

Installing springdoc-openapi and reading your first spec

The README's getting-started section says to add the springdoc-openapi-ui library to your project dependencies and that no additional configuration is needed. For Maven, the artifact is springdoc-openapi-starter-webmvc-ui under group org.springdoc, with the version placeholder the README writes as last-release-version. Substitute the release you have verified.

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

Gradle users get the same artifact through a single implementation line. The README shows the coordinate with a latest tag; pin an explicit version in a real build so the spec does not shift under you between CI runs.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:latest'

Start the application and the two endpoints should be live. Open http://localhost:8080/v3/api-docs in a browser or with curl and you should get a JSON document listing your controller paths and operations. Open http://localhost:8080/swagger-ui.html and you should get the rendered HTML page backed by the official swagger-ui jars. If your app has a context path, both URLs are prefixed by it.

The one optional property the README documents changes where the UI lives. Put it in your Spring Boot configuration file and the UI moves to the path you name.

# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

The README also links a demo repository with Spring Boot 4 Web MVC, WebFlux, functional endpoint and Spring HATEOAS examples, which is a faster way to see the expected output shape than debugging your own first spec.

Version lines and the Spring Boot 4 migration

This is where most wasted afternoons happen. The README states that for Spring Boot v4 support you must use springdoc-openapi v3, and the release list shows v3.1.1 and v2.9.1 both published on 2026-09-06, with v3.1.0 before them on 2026-08-01. Two active lines, released in parallel. The versioning section explains the policy: major increments are released in lockstep with Spring Boot major releases and may include incompatible or breaking changes, while minor and patch releases follow standard SemVer for backwards-compatible features and fixes.

Read that as a coupling contract. Your springdoc major is determined by your Spring Boot major, not by your appetite for new features. If you are on Spring Boot 4, v3 is the line; the v2.9.1 release is not a fallback for you. Conversely, if you have not moved to Boot 4, pulling v3 because it is numerically newer is a mistake the versioning policy explicitly warns about.

The parallel release dates are also the honest signal about maintenance. Two lines patched on the same day suggests both are being kept alive, which is good news for teams mid-migration, but it also means you carry a migration cost you did not choose. The README points to CHANGELOG.md for the full release history, and that file is where the breaking changes between majors will be enumerated. Read it before you bump a major, not after.

Where springdoc-openapi is the wrong tool

Runtime inference has a structural weakness: the spec only exists when the application is running and the context has loaded. If your workflow needs a committed OpenAPI file that a linter, a contract test or a client generator consumes in CI without booting the service, you are using the wrong shape of tool. The README's documented paths are all served endpoints, and nothing in the getting-started section describes producing the document as a build step.

There is a related trap with Spring Security. The README's table of contents includes a section titled When Spring Security is enabled, and that is not decoration. A secured application will typically reject unauthenticated requests to /v3/api-docs and /swagger-ui.html, so the endpoints exist but return a 401 or a redirect. The README does not spell out the fix in the excerpted text, so treat the security section as required reading rather than assuming the paths are public.

A third boundary is dynamic routing. The library infers semantics from Spring configurations, class structure and annotations. Controllers registered programmatically from configuration data, or routes whose parameters are built at runtime, give the scanner little to work with. The WebFlux case has a similar edge: the README documents webflux support with annotated controllers, and functional endpoints appear only in the demo list. If your WebFlux service is written in the functional style, verify the output against the demo before assuming parity with the annotated path.

Finally, the management port. The README lists a section on using a separate management port, which exists precisely because the documentation endpoints and the application endpoints can end up on different ports. Get that wrong and you will be curling the wrong host.

Alternatives and how the approach differs

The obvious comparison is Springfox, which is the tool springdoc-openapi replaced in most Spring projects. Both generate an OpenAPI-style description from Spring annotations, but the difference is the target specification and the maintenance coupling. Springfox was built around Swagger 2 semantics and its OpenAPI 3 support came later and incompletely. springdoc-openapi was designed for OpenAPI 3 from the start, and its major version tracks the Spring Boot major, which is why the README can promise Boot 4 support with a v3 line rather than a compatibility matrix. If you are starting on Boot 4, Springfox is not a live option.

The second alternative is a design-first toolchain, where you author the OpenAPI document by hand or in an editor and generate server stubs or validation from it. The trade is inverted. Design-first gives you a reviewable artifact in version control and a spec that exists before deployment, at the cost of keeping the document and the controllers in sync manually or through a generator step. springdoc-openapi gives you zero drift by construction, at the cost of a spec you can only observe from a running instance. Teams that treat the OpenAPI file as a contract reviewed by other teams often prefer design-first for exactly this reason; teams that want documentation that cannot go stale prefer springdoc-openapi.

Within the project there is a third choice worth naming: the README documents integrating the library without swagger-ui, and the repository ships springdoc-openapi-starter-webmvc-api alongside the -ui starter. If you only want the JSON description and plan to render it in your own portal, the api starter is the narrower dependency.

Licence, maintenance and upgrade cost

The project is Apache-2.0. For most commercial use that is a permissive licence with the usual attribution and notice obligations, and the repository carries COPYRIGHT and LICENSE files at the top level. Apache-2.0 also includes an express patent grant, which matters if you are shipping the library inside a product rather than using it only in development. None of this is legal advice; have your own counsel read the LICENSE file if the distinction affects your distribution model.

The maintenance picture is mixed in a way worth stating plainly. The last push to the default branch was on 2026-09-06, and v3.1.1 and v2.9.1 were both released that same day. That is a project being patched, not one that has gone quiet. But it is also a community project, as the README says, funded through Open Collective and GitHub sponsors, with security reports routed through Tidelift. There is no vendor SLA behind a bug you file. If your organisation needs a named party to escalate to, that gap is real.

The upgrade cost is dominated by the major-version coupling rather than by the library's own churn. Because majors land with Spring Boot majors and may include breaking changes, a Boot upgrade is also a springdoc upgrade, and the two have to be planned together. Minor and patch releases are backwards-compatible under SemVer, so routine bumps are cheap. Budget the expensive work for the major steps and read CHANGELOG.md at that point, not on every patch.

Editorial conclusion

Adopt springdoc-openapi if you run Spring Boot 4 and want the API description generated from the code you already have, without hand-writing a spec. Stay away if you need a spec that exists before the application starts, or if you are still on an older Spring Boot line and do not want the version migration. Before committing, verify which major you must use, check that springdoc-openapi-starter-webmvc-ui resolves for your build, and load /v3/api-docs and /swagger-ui.html on a running instance to confirm the paths your context path produces.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. springdoc/springdoc-openapi on GitHub