OpenAPI 3 Java Documentation With springdoc and Annotations
Document a Java REST API with OpenAPI 3: springdoc-openapi in Spring Boot, annotations for summaries and responses, security schemes and exporting the spec.

An API without a machine-readable description forces every consumer to read your code. OpenAPI is the standard description, and in Spring Boot the springdoc library generates it from the code you already have.
Add springdoc
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.8.9</version>
</dependency>Check the compatible version against your Spring Boot release on the springdoc site. Start the application and open:
/v3/api-docsfor the JSON,/v3/api-docs.yamlfor YAML./swagger-ui.htmlfor the interactive UI.
Out of the box it documents every @RestController mapping with parameters, request bodies and response types, using the types of the method signatures. The controller style is in writing a REST controller.
Describe operations
@RestController
@RequestMapping("/orders")
@Tag(name = "Orders", description = "Create and read orders")
class OrderController {
@Operation(summary = "Get an order by id")
@ApiResponses({
@ApiResponse(responseCode = "200", description = "The order"),
@ApiResponse(responseCode = "404", description = "No such order",
content = @Content(schema = @Schema(implementation = ProblemDetail.class)))
})
@GetMapping("/{id}")
OrderView get(@Parameter(description = "Order id", example = "42") @PathVariable long id) { ... }
}@Schema(description = "A customer order")
public record OrderView(
@Schema(example = "42") long id,
@Schema(description = "Customer login", example = "ada") String customer,
@Schema(description = "Total in minor units", example = "2500") long totalCents) { }Add annotations where inference is weak: error responses, examples, units. Bean Validation constraints (@NotBlank, @Size) are picked up automatically and shown as required fields and limits. Standard error responses are best described once, using the shape from problem details.
Security schemes
@Bean
OpenAPI api() {
return new OpenAPI()
.info(new Info().title("Orders API").version("1.0.0"))
.components(new Components().addSecuritySchemes("bearer",
new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")))
.addSecurityItem(new SecurityRequirement().addList("bearer"));
}This marks all operations as needing a bearer token and lets Swagger UI show an Authorize button. Override per operation with @SecurityRequirements for the public ones.
Group and filter
springdoc.group-configs[0].group=public
springdoc.group-configs[0].paths-to-match=/api/public/**
springdoc.packages-to-scan=dev.javahacks.orders
springdoc.swagger-ui.path=/docsGroups produce separate documents for separate audiences. Hide internal endpoints with @Hidden.
In production
The UI and the spec reveal your API's shape. If it is internal, disable the UI:
springdoc.swagger-ui.enabled=falseand protect /v3/api-docs with the same security as the API, or publish the exported file instead.
Export and use the spec
Generate the file in the build with the springdoc Maven plugin, which starts the app during integration-test and downloads the JSON. Commit it, or compare it in CI, so a pull request shows contract changes. Consumers can then generate clients, see OpenAPI Generator clients. Contract tests can validate responses against the spec.
Design first or code first
springdoc is code first: the spec follows the code. A design-first team writes the YAML, generates interfaces with OpenAPI Generator and implements them. Code first is faster to start and drifts less with a build check. Design first suits cross-team contracts. Pick one per API.
Keeping the documentation true
A generated specification is accurate only for what the annotations and types can express. It cannot know that an endpoint also returns 409 when a name is taken, or that a field has a limited set of values, unless you say so. Add @ApiResponse for the error cases, @Schema with example, description and allowableValues on important fields, and Bean Validation annotations such as @NotNull and @Size, which springdoc reads and turns into required and maxLength. Do the work on the endpoints other teams use, and skip it for internal ones.
Then stop the spec drifting. Export it in the build and commit the file, and a pull request that changes the API shows up as a diff of the specification, which a reviewer can read. A test that compares the generated document with the committed one fails the build when someone changes a response without updating the contract.
Exposure in production
The documentation endpoints list every route and parameter. For a public API that is the point. For an internal one, it hands an attacker a map. Turn them off in production with springdoc.api-docs.enabled=false and springdoc.swagger-ui.enabled=false in the production profile, or protect them with the same authentication as the API. The version of springdoc has to match your Spring Boot line, so check its compatibility table when you upgrade Boot, because a mismatch shows as a startup error or an empty document and not as a clear message.
Using the spec downstream
The exported document is useful beyond the UI. It can generate typed clients, as in generating clients, drive contract tests and feed an API gateway. That only works when the spec is stable and correct, which is the argument for treating its generation as part of the build and not as a nice extra on a developer's machine. Give each operation a stable operationId, because generated client method names come from it, and renaming one is a breaking change for every consumer.
Documenting errors and security the way clients need them
Most generated documentation describes the happy path and leaves a client developer guessing about failures. Declare the error responses on the operation, with the same problem body you really return, so a generated client can parse a 404 or a 409 into a typed error instead of a string. Do it once through a global customizer or a shared annotation on the controllers, since repeating the same @ApiResponse on forty methods guarantees they drift apart. A client that reads the specification should know, without running the server, which statuses an operation can return and what each one means.
Security needs the same attention. Declare the security scheme once, as a bearer token or an OAuth flow, and attach it to the operations that require it, so the Swagger UI shows an Authorize button and generated clients know to send the header. Mark the public endpoints explicitly as having no security requirement. An operation without any declaration is ambiguous to a reader: it might be public, or the author might have forgotten.
A review step for the spec
Treat a change to the exported document as part of the pull request. A reviewer who sees a removed field or a changed type in the diff can ask whether it is a breaking change, which is a question nobody asks while reading Java. Tools such as openapi-diff can run in the build and fail on a breaking change against the main branch, which turns the review into a rule.
Versioning the API description
When the API gets a second version, keep one document per version and publish both, for instance /v3/api-docs/v1 and /v3/api-docs/v2 through springdoc's grouped configuration. Consumers pin to the version they built against, and you can show a deprecation notice in the old document with the deprecated flag on its operations while the new one is live. Without that, a client team learns about a removal from an error in production.
Where this does not apply
For Jakarta REST services, the MicroProfile OpenAPI and Quarkus quarkus-smallrye-openapi generate the same format. The reference is the OpenAPI Specification, and springdoc documentation lists the properties.


