Skip to main content
PreparationZone Logo
PrepZone

OpenAPI with Springdoc

Auto-generated API docs, Swagger UI, and keeping documentation in sync with code.

Pass checkpoint below

Why this matters

  • API documentation that drifts from implementation is worse than no documentation — springdoc generates specs from annotations automatically.
  • Swagger UI lets frontend teams and QA explore endpoints without reading source code.
  • OpenAPI specs enable client code generation and contract testing in CI pipelines.

OpenAPI purpose

L1 · Fresher

Machine-readable API description powers Swagger UI and client generators for BookStore consumers.

Springdoc setup

L2 · Intermediate

Add springdoc-openapi-starter-webmvc-ui — annotations like @Operation document endpoints next to code.

Keeping docs accurate

L3 · Advanced

Treat OpenAPI as part of CI — breaking changes in DTOs should fail contract tests or diff checks.

Security in docs

L4 · Expert

Document OAuth2 schemes and required scopes so gateway teams configure clients without reading source.

Servlet FilterEncoding, CORS
Security Filter ChainAuth, CSRF
DispatcherServlet
HandlerInterceptorPre/post handle
Controller
Filters run before DispatcherServlet. Interceptors wrap the controller. Security filters sit in their own chain.

Add springdoc

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

Start BookStore and visit:

Documentation URLs

  • Swagger UI: http://127.0.0.1:8080/swagger-ui.html
  • Raw spec: http://127.0.0.1:8080/v3/api-docs

No configuration needed for basic usage — springdoc discovers all @RestController endpoints.

The rest of this guide is part of Pro

Free covers every fresher guide in full. Pro unlocks Senior, Staff and Architect guides across every track.

Still to come · 6 sections

  • Enriching documentation
  • Documenting DTOs
  • Global API info
  • Customising paths
  • Grouping APIs
  • Exporting the spec in CI

Test yourself

Answer these before moving on — recall is what makes it stick.