OpenAPI and Swagger documentation

OpenAPI is a machine-readable description of a REST API.

🔎 Unravel this example Prerequisites (1)

Learn these first

Spring REST controllers

At a glance

Mental model

The restaurant menu for your API.

What happens, in order

1With springdoc, adding the dependency is enough: it reads your controllers and publishes /v3/api-docs (JSON) and /swagger-ui.html
2Annotations refine it: @Operation(summary = "Create order") describes a method, @ApiResponse(responseCode = "404") documents an outcome, @Schema(description = ..., example = ...) documents a field, @Tag groups endpoints
3Security is declared with @SecurityScheme (bearer JWT, OAuth2) and @SecurityRequirement on operations, so the UI offers an Authorize button
4The old Swagger 2 style (@Api, @ApiOperation, Docket) belongs to springfox, which is unmaintained; new code uses springdoc and the io.swagger.v3 annotations

Remember

Treat the spec as a contract
Do not expose internal endpoints or model fields in public documentation
springdoc scans the handler mappings at runtime, builds an OpenAPI object with models derived from the Java types through the Jackson/Swagger model resolver, merges your annotations and serializes it

Watch out

Documentation that disagrees with the codeExposing swagger-ui in production by accidentNo error responses documentedMixing springfox and springdoc annotations

Example (highlighted lines explain it)

@RestController@Tag(name = "Orders")public class OrderController {    @Operation(summary = "Create an order", description = "Creates an order for the logged-in customer")    @ApiResponse(responseCode = "201", description = "Created")    @ApiResponse(responseCode = "400", description = "Invalid request")    @PostMapping("/orders")    public ResponseEntity<OrderDto> create(@RequestBody CreateOrderRequest request) {        return ResponseEntity.status(201).body(service.create(request));    }}

line 4 uses Operation, the core of OpenAPI and Swagger documentation
line 5 uses ApiResponse, the core of OpenAPI and Swagger documentation
line 6 uses ApiResponse, the core of OpenAPI and Swagger documentation

Read the full explanation (about 1 min)

OpenAPI is a machine-readable description of a REST API. Annotations on controllers produce it, tools such as Swagger UI turn it into interactive documentation, and clients and tests can be generated from it.

A mental model

The restaurant menu for your API. It lists every dish (endpoint), what you must say to order it (parameters) and what arrives on the plate (responses), so guests never need to ask the kitchen.

How it works

With springdoc, adding the dependency is enough: it reads your controllers and publishes /v3/api-docs (JSON) and /swagger-ui.html.

Annotations refine it: @Operation(summary = "Create order") describes a method, @ApiResponse(responseCode = "404") documents an outcome, @Schema(description = ..., example = ...) documents a field, @Tag groups endpoints.

Security is declared with @SecurityScheme (bearer JWT, OAuth2) and @SecurityRequirement on operations, so the UI offers an Authorize button.

The old Swagger 2 style (@Api, @ApiOperation, Docket) belongs to springfox, which is unmaintained; new code uses springdoc and the io.swagger.v3 annotations.

Going deeper

Treat the spec as a contract. Generate the spec in the build, store it, and diff it in review (or use a breaking-change checker), so an innocent refactoring does not break clients.

Do not expose internal endpoints or model fields in public documentation. Use @Hidden or groups, and disable the UI in production unless it is intended.

Design-first is the alternative: write the YAML spec first and generate server interfaces and clients from it, so documentation can never drift from code.

Under the hood

springdoc scans the handler mappings at runtime, builds an OpenAPI object with models derived from the Java types through the Jackson/Swagger model resolver, merges your annotations and serializes it. Swagger UI is a static JavaScript application served from a webjar that loads that JSON.

Common mistakes

Documentation that disagrees with the code.
Exposing swagger-ui in production by accident.
No error responses documented.
Mixing springfox and springdoc annotations.

How Unravel recognises it

When you paste code, Unravel looks for these signs of openapi and swagger documentation. Spotting them yourself is a good habit when you read unfamiliar code:

Annotations: @Operation @Schema @ApiResponse @ApiResponses @ApiOperation @Api @ApiModel @ApiModelProperty @OpenAPIDefinition @SecurityScheme @SecurityRequirement @Hidden @EnableSwagger2 @ApiParam
Types: OpenAPI GroupedOpenApi OpenApiCustomizer Docket

Part of a learning path

Building and documenting APIs · previous: Spring REST controllers · next: Custom Jackson serialization and modules

Related concepts

Spring REST controllersSpring Jackson JSONI/O and data

Frequently asked questions

What is OpenAPI and Swagger documentation?

What are the most common mistakes with OpenAPI and Swagger documentation?

Documentation that disagrees with the code. Exposing swagger-ui in production by accident. No error responses documented. Mixing springfox and springdoc annotations.

How can I see OpenAPI and Swagger documentation in real code?

Paste your own Java into Unravel and it will point out where openapi and swagger documentation appears, explain how it works at the detail level you choose, and draw the flow of the code around it.