Provides patterns to generate comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications. Use when setting up API documentation, configuring Swagger UI, adding OpenAPI annotations, implementing security documentation, or enhancing REST endpoints with examples and schemas.
中文简介正在准备中。当前显示原文说明。
查看安装方法安装前可以查看交给 AI 代理的指令内容。
SpringDoc OpenAPI automates generation of OpenAPI 3.0 documentation for Spring Boot projects with a Swagger UI web interface for exploring and testing APIs.
| Concept | Description |
|---|---|
| Dependencies | springdoc-openapi-starter-webmvc-ui for WebMvc, springdoc-openapi-starter-webflux-ui for WebFlux |
| Configuration | application.yml with springdoc.api-docs.* and springdoc.swagger-ui.* properties |
| Access Points | OpenAPI JSON: /v3/api-docs, Swagger UI: /swagger-ui/index.html |
| Core Annotations | @Tag, @Operation, @ApiResponse, @Parameter, @Schema, @SecurityRequirement |
| Security | Configure security schemes in OpenAPI bean, apply with @SecurityRequirement |
| Pagination | Use @ParameterObject with Spring Data Pageable |
Add SpringDoc starter for your application type (WebMvc or WebFlux). See dependency-setup.md for Maven/Gradle configuration.
Set basic configuration in application.yml:
springdoc:
api-docs:
path: /api-docs
swagger-ui:
path: /swagger-ui.html
operationsSorter: method
See configuration.md for advanced options.
Use OpenAPI annotations to add descriptive information:
@RestController
@Tag(name = "Book", description = "Book management APIs")
public class BookController {
@Operation(summary = "Get book by ID")
@ApiResponse(responseCode = "200", description = "Book found")
@GetMapping("/{id}")
public Book findById(@PathVariable Long id) { }
}
See controller-documentation.md for patterns.
Apply @Schema annotations to DTOs:
@Schema(description = "Book entity")
public class Book {
@Schema(example = "1", accessMode = Schema.AccessMode.READ_ONLY)
private Long id;
@Schema(example = "Clean Code", required = true)
private String title;
}
See model-documentation.md for validation patterns.
Set up security schemes in OpenAPI bean:
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.components(new Components()
.addSecuritySchemes("bearer-jwt", new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")
)
);
}
Apply with @SecurityRequirement(name = "bearer-jwt") on controllers. See security-configuration.md.
Use @ParameterObject for Spring Data Pageable:
@GetMapping("/paginated")
public Page<Book> findAll(@ParameterObject Pageable pageable) {
return repository.findAll(pageable);
}
Access Swagger UI at /swagger-ui/index.html to verify documentation completeness.
Configure API grouping, versioning, and build plugins. See advanced-configuration.md and build-integration.md.
@ExampleObject for realistic examples@ParameterObject for complex parameters: Especially for Pageable, custom filter objects@Tag: Organize API by domain entities or features@SecurityRequirement where authentication needed@Hidden or create separate API groups@Schema annotations@SecurityRequirement annotations@Operation(hidden = true)) are still visible in code and may leak through other documentation tools@RestController
@Tag(name = "Books", description = "Book management APIs")
@RequestMapping("/api/books")
public class BookController {
@Operation(
summary = "Get book by ID",
description = "Retrieves detailed information about a specific book"
)
@ApiResponse(responseCode = "200", description = "Book found")
@ApiResponse(responseCode = "404", description = "Book not found")
@GetMapping("/{id}")
public Book getBook(@PathVariable Long id) {
return bookService.findById(id);
}
@Operation(summary = "Create new book")
@SecurityRequirement(name = "bearer-jwt")
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public Book createBook(@Valid @RequestBody CreateBookRequest request) {
return bookService.create(request);
}
}
@Schema(description = "Book entity")
public class Book {
@Schema(description = "Unique identifier", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
private Long id;
@Schema(description = "Book title", example = "Clean Code", required = true)
@NotBlank
@Size(min = 1, max = 200)
private String title;
@Schema(description = "Author name", example = "Robert C. Martin")
@NotBlank
private String author;
@Schema(description = "Price in USD", example = "29.99", minimum = "0")
@NotNull
@DecimalMin("0.0")
private BigDecimal price;
}
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("Book API")
.version("1.0.0")
.description("REST API for book management"))
.components(new Components()
.addSecuritySchemes("bearer-jwt", new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT"))
.addSecuritySchemes("api-key", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name("X-API-Key")));
}
spring-boot-rest-api-standards — REST API design standardsspring-boot-dependency-injection — Dependency injection patternsunit-test-controller-layer — Testing REST controllersspring-boot-actuator — Production monitoring and management还没有评价。欢迎分享你的使用感受。
无需登录即可发表。欢迎分享使用感受、提问，或说明在哪些环境下无法运行。
还没有评论。来写第一条吧。
Use when adding monitoring, metrics, logging, or tracing to Spring AI or LLM integration code. Covers token tracking, latency measurement, cost estimation, and prompt/response logging. Use when user mentions AI monitoring, token costs, or LLM observability.
中文简介正在准备中。当前显示原文说明。
Provides expert knowledge for building modern native Android apps using Kotlin, Jetpack Compose, Material Design 3, MVI architecture, Hilt dependency injection, and Media3/ExoPlayer.
中文简介正在准备中。当前显示原文说明。
Design, implement, review, and audit Android Jetpack Compose UI/UX for phone interfaces. Use when a request concerns concrete Compose layout, components, interaction, accessibility, or visual behavior. Do not activate for framework or dependency presence alone; non-UI Android work is excluded.
中文简介正在准备中。当前显示原文说明。
Provides expert knowledge for designing, implementing, and managing REST API versioning strategies with deprecation workflows.
中文简介正在准备中。当前显示原文说明。
Provides expert knowledge for building Astro 5+ sites with Islands Architecture, Content Collections, TypeScript, and performance-first rendering strategies.
中文简介正在准备中。当前显示原文说明。
Audits token storage mechanisms to prevent XSS-based JWT theft.
中文简介正在准备中。当前显示原文说明。