OpenAPI Documentation with SpringDoc
Fast recall
Quick revision
Core answer
Practical ability to document APIs for other teams
Using the deprecated springfox library (Swagger 2) instead of springdoc (OpenAPI 3)
Mention using the spec for contract-first development and client code generation
Interview-ready guide
Interview answer
Springdoc generates OpenAPI 3.x documentation from your Spring MVC controllers automatically — no XML, no separate doc server. The generated spec is the contract that clients, tests, and SDK generators consume.
Setup
- Add
springdoc-openapi-starter-webmvc-uidependency - Swagger UI is available at
/swagger-ui.html; the raw OpenAPI JSON/YAML at/v3/api-docs - Springdoc introspects
@RequestMapping,@RequestBody,@PathVariable, return types — zero additional annotations needed for basic documentation
Enriching the documentation
@Operation(summary = "Create order", description = "...")— describes the endpoint@ApiResponse(responseCode = "201", description = "Order created")— documents response codes@Schema(description = "ISO 4217 currency code", example = "USD")— documents DTO fields with examples
Securing Swagger UI
- Configure
@SecurityScheme(type = SecuritySchemeType.HTTP, scheme = "bearer")on a configuration class - Annotate secured endpoints with
@SecurityRequirement(name = "bearerAuth") - Developers click 'Authorize', enter a JWT, and test protected endpoints directly from the UI
Export the spec at /v3/api-docs.yaml and use openapi-generator-cli to produce type-safe client libraries — one source of truth for the API contract shared between backend and frontend teams.
OpenAPI Documentation with SpringDoc
Direct Answer
Use springdoc-OpenAPI-starter-webmvc-ui to auto-generate OpenAPI 3 spec from your code. Enrich with @Operation, @ApiResponse, and @Schema annotations. Expose the UI at /Swagger-ui.html.
Common Mistakes & Pitfalls
Using the deprecated springfox library (Swagger 2) instead of springdoc (OpenAPI 3)
Check your understanding
Answer these without looking back at the article.
- How do you disable Swagger in production environments?
- How do you generate client SDKs from an OpenAPI spec?
- What is the difference between Swagger UI and ReDoc?
Related interview prep categories
1Want a guided curriculum order?
These modules are also sequenced in our flagship backend interview track — open it when you prefer an ordered path instead of browsing by topic.