Spring Boot and API documentation generation (OpenAPI)?

Question

Accepted Answer

**OpenAPI (Swagger)** — a standard for describing REST APIs. **springdoc-openapi** automatically generates documentation from controller annotations. **Simple analogy:** OpenAPI is like IKEA instructions. It describes every endpoint: URL, parameters, request body, response, errors. A frontend developer can read and understand without reading code. Or think of it as a table of contents for your API — it lists every chapter (endpoint), what inputs it accepts, and what it outputs. **Why it matters:** Without API documentation, frontend developers, mobile developers, and third-party integrators must read your Java source code to understand your API. OpenAPI generates a living, interactive documentation that is always in sync with your code because it is generated from the code itself. **Dependency:** ```xml org.springdoc springdoc-openapi-starter-webmvc-ui 2.3.0 ``` **Controller with annotations:** ```java @Tag(name = "Users", description = "User management") @RestController @RequestMapping("/api/users") public class UserController { @Operation(summary = "Get user by ID") @ApiResponses({ @ApiResponse(responseCode = "200", description = "User found"), @ApiResponse(responseCode = "404", description = "Not found", content = @Content(schema = @Schema(implementation = ErrorResponse.class))) }) @GetMapping("/{id}") public ResponseEntity getUser( @Parameter(description = "User ID", example = "1") @PathVariable Long id) { return ResponseEntity.ok(service.findById(id)); } @Operation(summary = "Create user") @io.swagger.v3.oas.annotations.parameters.RequestBody( description = "New user data" ) @PostMapping public ResponseEntity create(@Valid @RequestBody CreateUserRequest request) { return ResponseEntity.ok(service.create(request)); } @Operation(summary = "Search users") @GetMapping public Page search( @ParameterObject Pageable pageable, @RequestParam(required = false) String name) { return service.search(name, pageable); } } ``` **Swagger UI:** http://localhost:8080/swagger-ui/index.html **OpenAPI JSON:** http://localhost:8080/v3/api-docs **Grouping (multiple API docs):** ```java @Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("public") .pathsToMatch("/api/public/**") .build(); } @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group("admin") .pathsToMatch("/api/admin/**") .build(); } ``` **Hiding internal endpoints:** ```java @Hidden // This endpoint won't appear in docs @GetMapping("/api/internal/health") public String internalHealth() { return "ok"; } ``` **Common mistakes:** - **Exposing Swagger UI in production** — disable with `springdoc.api-docs.enabled=false` and `springdoc.swagger-ui.enabled=false` in production profiles. - **Missing `@Schema` on DTOs** — without it, the docs show field names but no descriptions or examples. - **Not versioning the API** — add API version info via `@OpenAPIDefinition(info = @Info(title = "API", version = "1.0"))`.

Java: Spring Boot and API documentation generation (OpenAPI)?