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 · FresherMachine-readable API description powers Swagger UI and client generators for BookStore consumers.
Springdoc setup
L2 · IntermediateAdd springdoc-openapi-starter-webmvc-ui — annotations like @Operation document endpoints next to code.
Keeping docs accurate
L3 · AdvancedTreat OpenAPI as part of CI — breaking changes in DTOs should fail contract tests or diff checks.
Security in docs
L4 · ExpertDocument OAuth2 schemes and required scopes so gateway teams configure clients without reading source.
Add springdoc
<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.