# Spring Boot OpenAPI 文档与 SpringDoc 在 Spring Boot 3.x 应用程序中使用 SpringDoc OpenAPI 3.0 和 Swagger UI 实现全面的 REST API 文档。 ## 何时使用当您需要执行以下操作时，请使用此技能： * 在 Spring Boot 3.x 项目中设置 SpringDoc OpenAPI * 为 REST API 生成 OpenAPI 3.0 规范 * 配置和自定义 Swagger UI * 添加详细的API文档和注释 * 记录请求/响应模型并进行验证 * 实施 API 安全文档（JWT、OAuth2、基本身份验证） * 记录可分页和可排序端点 * 向 API 端点添加示例和模式 * 以编程方式自定义 OpenAPI 定义 * 为WebMvc或WebFlux应用程序生成API文档 * 支持多个API组和版本 * 记录错误响应和异常处理程序 * 将 JSR-303 Bean 验证添加到 API 文档中 * 支持基于Kotlin的Spring Boot API ## 设置依赖关系 ### 添加 Maven 依赖项 <依赖关系> org.springdoc springdoc-openapi-starter-webmvc-ui 2.8.13 // 使用最新的稳定版本 <依赖关系> com.github.therapi therapi-runtime-javadoc 0.15.0 // 使用最新的稳定版本 <范围>提供 <依赖关系> org.springdoc springdoc-openapi-starter-webflux-ui 2.8.13 // 使用最新的稳定版本 ### 添加 Gradle 依赖项 // 标准 WebMVC 支持实现 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.13' // 可选：therapi-runtime-javadoc 用于 JavaDoc 支持实现 'com.github.therapi:therapi-runtime-javadoc:0.15.0' // WebFlux 支持实现 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.8.13' ## 配置 SpringDoc ### 基本配置 # 应用程序. 属性 springdoc.api-docs.path=/api-docs springdoc.swagger-ui.path=/swagger-ui-custom.html springdoc.swagger-ui.operationsSorter=方法 springdoc.swagger-ui.tagsSorter=alpha springdoc.swagger-ui.enabled=true springdoc.api-docs.enabled=true springdoc.packages-to-scan=com.example.controller springdoc.paths-to-match=/api/** # 应用程序.yml 弹簧文档： API 文档：路径：/api-docs 启用：真招摇用户界面：路径：/swagger-ui.html 启用：真操作排序器：方法标签排序器：alpha tryItOutEnabled: true 要扫描的包：com.example.controller 匹配路径：/api/** ### 访问端点配置后： * **OpenAPI JSON** ：`http://localhost:8080/v3/api-docs` * **OpenAPI YAML** ：`http://localhost:8080/v3/api-docs.yaml` * **Swagger UI** ：`http://localhost:8080/swagger-ui/index.html` ## 文档控制器 ### 基本控制器文档导入 io.swagger.v3.oas.annotations.Operation; 导入 io.swagger.v3.oas.annotations.Parameter; 导入 io.swagger.v3.oas.annotations.responses.ApiResponse; 导入 io.swagger.v3.oas.annotations.responses.ApiResponses; 导入 io.swagger.v3.oas.annotations.tags.Tag; 导入 org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/books") @Tag(name = "图书",description = "图书管理接口") 公共类 BookController { @操作（摘要 = "通过 ID 检索一本书", description = "通过指定 ID 获取 Book 对象。响应包括 id、标题、作者和描述。" ） @ApiResponses(值 = { @ApiResponse( 响应代码 = "200", description = "成功检索图书", 内容 = @Content(架构 = @Schema(实现 = Book.class)) ), @ApiResponse( 响应代码 = "404", 描述=“找不到书” ） }) @GetMapping("/{id}") 公共图书 findById( @Parameter(description = "要检索的书籍 ID", required = true) @PathVariable长id ）{ 返回repository.findById(id) .orElseThrow(() -> new BookNotFoundException()); } } ### 文档请求机构导入 io.swagger.v3.oas.annotations.parameters.RequestBody; 导入 io.swagger.v3.oas.annotations.media.ExampleObject; @Operation(summary = "创建一本新书") @PostMapping @ResponseStatus(HttpStatus.CREATED) 公共图书 createBook( @RequestBody( 描述=“要创建的书”，必需=真，内容=@内容( 架构 = @Schema(实现 = Book.class), 示例 = @ExampleObject( 值=“”“ { "title": "干净的代码", “作者”：“罗伯特·C·马丁”， “书号”：“978-0132350884”， “description”：“敏捷软件工艺手册” } ”“” ）））书本）{ 返回存储库.保存（书）； } ## 文档模型 ### 具有验证的实体导入 io.swagger.v3.oas.annotations.media.Schema; 导入 jakarta.validation.constraints.*; @实体 @Schema(description = "代表已出版书籍的书籍实体") 公开课书{ @Id @GenerateValue(策略 = GenerationType.IDENTITY) @Schema(描述 = "唯一标识符"，示例 = "1"，accessMode = Schema.AccessMode.READ_ONLY) 私人长ID； @NotBlank(message = "标题为必填项") @大小（最小值= 1，最大值= 200） @Schema(description = "书名", example = "干净的代码", required = true, maxLength = 200) 私有字符串标题； @Pattern(regexp = "^(?:ISBN(?:-1[03])?:? )?(?=[0-9X]{10}$|(?=(?:[0-9]+[- ]){3})[- 0-9X]{13}$|97[89][0-9]{10}$|(?=(?:[0-9]+[- ]){4})[- 0-9]{17}$)(?:97[89][- ]?)?[0-9]{1,5}[- ]?[0-9]+[- ]?[0-9]+[- ]?[0-9X]$") @Schema(描述 =“ISBN 号”，示例 =“978-0132350884”) 私有字符串 isbn； // 附加字段、构造函数、getter、setter } ### 隐藏字段 @Schema（隐藏= true）私有字符串内部字段； @JsonIgnore @Schema(accessMode = Schema.AccessMode.READ_ONLY) 私有 LocalDateTime 创建于； ## 文件安全 ### JWT 承载身份验证导入 io.swagger.v3.oas.annotations.security.SecurityRequirement; 导入 io.swagger.v3.oas.models.Components; 导入 io.swagger.v3.oas.models.security.SecurityScheme; @配置公共类 OpenAPISecurityConfig { @豆子公共 OpenAPI 自定义OpenAPI() { 返回新的 OpenAPI() .组件（新组件（） .addSecuritySchemes("bearer-jwt", new SecurityScheme() .type(SecurityScheme.Type.HTTP) .scheme("承载者") .bearerFormat("JWT") .description("JWT 身份验证") ））； } } // 应用安全要求 @RestController @RequestMapping("/api/books") @SecurityRequirement(name = "bearer-jwt") 公共类 BookController { // 所有端点都需要 JWT 身份验证 } ### OAuth2 配置导入 io.swagger.v3.oas.models.security.OAuthFlow; 导入 io.swagger.v3.oas.models.security.OAuthFlows; 导入 io.swagger.v3.oas.models.security.Scopes； @豆子公共 OpenAPI 自定义OpenAPI() { 返回新的 OpenAPI() .组件（新组件（） .addSecuritySchemes("oauth2", new SecurityScheme() .type(SecurityScheme.Type.OAUTH2) .flows(新的 OAuthFlows() .authorizationCode(new OAuthFlow() .authorizationUrl("https://auth.example.com/oauth/authorize") .tokenUrl("https://auth.example.com/oauth/token") .scopes(新的范围() .addString("读取", "读取访问权限") .addString("写入", "写入权限") ）））））； } ## 文档分页 ### Spring Data 可分页支持导入 org.springdoc.core.annotations.ParameterObject; 导入 org.springframework.data.domain.Page; 导入 org.springframework.data.domain.Pageable; @Operation(summary = "获取分页图书列表") @GetMapping("/分页") 公共页面<书籍> findAllPaginated( @ParameterObject 可分页可分页）{ 返回repository.findAll(可分页); } ## 高级配置 ### 多个 API 组导入 org.springdoc.core.models.GroupedOpenApi; @豆子公共 GroupedOpenApi publicApi() { 返回 GroupedOpenApi.builder() .group("公共") .pathsToMatch("/api/public/**") .build(); } @豆子公共 GroupedOpenApi adminApi() { 返回 GroupedOpenApi.builder() .group("管理员") .pathsToMatch("/api/admin/**") .build(); } ### 自定义操作定制器导入 org.springdoc.core.customizers.OperationCustomizer; @豆子公共操作定制器定制操作（）{ 返回（操作，处理程序方法）-> { operation.addExtension("x-custom-field", "custom-value"); 返回操作； }; } ### 隐藏端点 @操作（隐藏= true） @GetMapping("/内部") 公共字符串内部端点（）{ return“从文档中隐藏”； } // 隐藏整个控制器 @隐藏 @RestController 公共类内部控制器{ // 所有端点隐藏 } ## 记录异常响应 ### 全局异常处理程序导入 org.springframework.web.bind.annotation.ExceptionHandler; 导入 org.springframework.web.bind.annotation.ResponseStatus; 导入 org.springframework.web.bind.annotation.RestControllerAdvice; @RestControllerAdvice 公共类 GlobalExceptionHandler { @ExceptionHandler(BookNotFoundException.class) @ResponseStatus(HttpStatus.NOT_FOUND) @操作（隐藏= true）公共ErrorResponsehandleBookNotFound（BookNotFoundException ex）{ 返回新的 ErrorResponse("BOOK_NOT_FOUND", ex.getMessage()); } @ExceptionHandler(ValidationException.class) @ResponseStatus(HttpStatus.BAD_REQUEST) @操作（隐藏= true）公共ErrorResponsehandleValidation（ValidationException ex）{ 返回新的 ErrorResponse("VALIDATION_ERROR", ex.getMessage()); } } @Schema(描述 = "错误响应") 公共记录错误响应（ @Schema(描述 =“错误代码”，示例 =“BOOK_NOT_FOUND”) 字符串代码， @Schema(description = "错误消息", example = "未找到 ID 为 123 的图书") 字符串消息， @Schema（描述=“时间戳”，示例=“2024-01-15T10：30：00Z”） LocalDateTime 时间戳）{} ## 构建集成 ### Maven 插件 <插件> org.springdoc springdoc-openapi-maven-plugin <版本>1.4 <处决> <执行> 集成测试 <目标> <目标>生成 <配置> http://localhost:8080/v3/api-docs <输出文件名>openapi.json ${project.build.directory} ### Gradle 插件插件{ id 'org.springdoc.openapi-gradle-plugin' 版本 '1.9.0' } 开放API { apiDocsUrl =“http://localhost:8080/v3/api-docs” 输出目录 = 文件（“$buildDir/docs”）输出文件名 = "openapi.json" } ## 示例 ### 完整的 REST 控制器示例导入 io.swagger.v3.oas.annotations.Operation; 导入 io.swagger.v3.oas.annotations.Parameter; 导入 io.swagger.v3.oas.annotations.media.Content；导入 io.swagger.v3.oas.annotations.media.Schema; 导入 io.swagger.v3.oas.annotations.responses.ApiResponse; 导入 io.swagger.v3.oas.annotations.responses.ApiResponses; 导入 io.swagger.v3.oas.annotations.tags.Tag; 导入 io.swagger.v3.oas.annotations.security.SecurityRequirement; 导入 org.springframework.data.domain.Page; 导入 org.springframework.data.domain.Pageable; 导入 org.springdoc.core.annotations.ParameterObject; 导入 org.springframework.web.bind.annotation.*; 导入 jakarta.validation.Valid; @RestController @RequestMapping("/api/books") @Tag(name = "图书",description = "图书管理接口") @SecurityRequirement(name = "bearer-jwt") 公共类 BookController { 私人最终 BookService bookService；公共 BookController(BookService bookService) { this.bookService = bookService; } @Operation(summary = "获取所有书籍") @ApiResponses(值 = { @ApiResponse( 响应代码 = "200", 描述=“找到所有书籍”，内容=@内容( 媒体类型=“应用程序/json”，数组 = @ArraySchema(模式 = @Schema(实现 = Book.class)) ）） }) @GetMapping 公共列表 getAllBooks() { 返回 bookService.getAllBooks(); } @Operation(summary = "获取分页书籍") @GetMapping("/分页") 公共页面 getBooksPaginated(@ParameterObject Pageable pageable) { 返回 bookService.getBooksPaginated(可分页); } @Operation(summary = "通过ID获取图书") @ApiResponses(值 = { @ApiResponse(responseCode = "200", 描述 = "找到书"), @ApiResponse(responseCode = "404", 描述 = "未找到图书") }) @GetMapping("/{id}") 公共图书 getBookById(@PathVariable Long id) { 返回 bookService.getBookById(id); } @Operation(summary = "创建新书") @ApiResponses(值 = { @ApiResponse(responseCode = "201", description = "图书创建成功"), @ApiResponse(responseCode = "400", 描述 = "无效输入") }) @PostMapping @ResponseStatus(HttpStatus.CREATED) 公共图书 createBook(@Valid @RequestBody Book book) { 返回 bookService.createBook(book); } @Operation(summary = "更新书籍") @ApiResponses(值 = { @ApiResponse(responseCode = "200", 描述 = "图书已更新"), @ApiResponse(responseCode = "404", 描述 = "未找到图书") }) @PutMapping("/{id}") 公共图书 updateBook(@PathVariable Long id, @Valid @RequestBody Book book) { 返回 bookService.updateBook(id, book); } @Operation(summary = "删除图书") @ApiResponses(值 = { @ApiResponse(responseCode = "204", description = "图书已删除"), @ApiResponse(responseCode = "404", 描述 = "未找到图书") }) @DeleteMapping("/{id}") @ResponseStatus(HttpStatus.NO_CONTENT) 公共无效deleteBook（@PathVariable长id）{ bookService.deleteBook(id); } } ## 最佳实践 1. **使用描述性操作摘要和描述** * 摘要：简短、清晰的陈述（< 120 个字符） * 描述：带有用例的详细解释 2. **记录所有响应代码** * 包括成功(2xx)、客户端错误(4xx)、服务器错误(5xx) * 为每个内容提供有意义的描述 3. **向请求/响应主体添加示例** * 使用`@ExampleObject`作为实际示例 * 包括相关的边缘情况 4. **利用 JSR-303 验证注释** * SpringDoc从验证注释自动生成约束 * 减少代码和文档之间的重复 5. **对复杂参数使用`@ParameterObject`** * 对于可分页、自定义过滤器对象特别有用 * 保持控制器方法干净 6. **使用@Tag对相关端点进行分组** * 按领域实体或功能组织 API * 跨控制器使用一致的标签名称 7. **文件安全要求** * 在需要身份验证的地方应用`@SecurityRequirement` * 在 OpenAPI bean 中全局配置安全方案 8. **适当隐藏内部/管理端点** * 使用`@Hidden`或创建单独的API组 * 防止暴露内部实现细节 9. **自定义 Swagger UI 以获得更好的用户体验** * 启用过滤、排序、试用功能 * 设置适当的默认行为 10. **对 API 文档进行版本控制** * 在 OpenAPI 信息中包含版本 * 为版本化 API 考虑多个 API 组 ## 常用注解参考 ### 核心注释 * `@Tag`：标签下的分组操作 * `@Operation`：描述单个API操作 * `@ApiResponse` / `@ApiResponses`：文档响应代码 * `@Parameter`：记录单个参数 * `@RequestBody`：文档请求体（OpenAPI版本） * `@Schema`：文档模型架构 * `@SecurityRequirement`：对操作应用安全性 * `@Hidden`：从文档中隐藏 * `@ParameterObject`：将复杂对象记录为参数 ### 验证注释（自动记录） * `@NotNull`、`@NotBlank`、`@NotEmpty`：必填字段 * `@Size(min, max)`：字符串/集合长度约束 * `@Min`, `@Max`: 数值范围限制 * `@Pattern`: 正则表达式验证 * `@Email`: 电子邮件验证 * `@DecimalMin`, `@DecimalMax`: 小数约束 * `@Positive`、`@PositiveOrZero`、`@Negative`、`@NegativeOrZero` ## 故障排除有关常见问题和解决方案，请参阅@references/troubleshooting.md 中的故障排除指南 ## 相关技能 * `spring-boot-rest-api-standards` \- REST API 设计标准 * `spring-boot-dependency-injection` \- 依赖注入模式 * `unit-test-controller-layer` \- 测试 REST 控制器 * `spring-boot-actuator` \- 生产监控与管理 ## 参考文献 * [全面的 SpringDoc 文档]() * [常见问题及解决方案]() * [SpringDoc官方文档]() * [OpenAPI 3.0 规范]() _OpenAPI 文档 v1.1 - 增强版_ ## 🔄 工作流程 > **Kaynak:** [SpringDoc 官方文档]() ### Aşama 1：配置 * **依赖项** ：`springdoc-openapi-starter-webmvc-ui`（Spring Boot 3 的 v2.x）ekle。 * **属性** ： `springdoc.api-docs.path` 和 `swagger-ui.path` değerlerini sabitle（自定义路径 kullanıyorsan）。 * **平台**：WebMVC 与 WebFlux ayrımına dikkat et（依赖项）。 ### Aşama 2：文档层 * **控制器**：`@Tag` 是组，`@Operation` 是她的端点。 * **模型**：DTO'ları `@Schema` ile tanımla，验证 anotasyonlarını (`@NotNull`) ekle (otomatik yansır)。 * **安全性**：全局安全方案（JWT/OAuth2）与端点“@SecurityRequirement”相关。 ### 阿萨玛 3：增强 * **示例**：使用“@ExampleObject”给出请求/响应主体的实际示例。 * **错误处理**：使用“@ApiResponse”在全局异常处理程序中记录错误响应格式。 * **生成** ：在 CI/CD 管道中使用 `springdoc-openapi-maven-plugin` 生成 `openapi.json`。 ### 检查点舞台|验证 ---|--- 1 | `/v3/api-docs` 是否返回 JSON？ 2 | Swagger UI 中的“试用”按钮是否有效（是否存在 CORS/Auth 问题）？ 3 |枚举值和必填字段是否正确显示在文档中？

OpenAPI 文档

包含技能