4. Springdoc-openapi特点
   4.1.添加API信息和安全文档
   该库使用 spring-boot 应用程序自动配置包来扫描 spring bean 中的以下注释：OpenAPIDefinition 和 Info。这些注释声明 API 信息：标题、版本、许可证、安全性、服务器、标签、安全性和外部文档。为了获得更好的文档生成性能，请在 spring 托管 bean 中声明 @OpenAPIDefinition 和 @SecurityScheme 注释。

4.2.使用 @ControllerAdvice 进行 REST 错误处理
要自动生成文档，请确保所有方法都使用注释声明 HTTP 代码响应：@ResponseStatus

4.3.禁用springdoc-openapi端点
要禁用springdoc-openapi端点（默认情况下为/v3/api-docs），请使用以下属性：

Disabling the /v3/api-docs endpoint

springdoc.api-docs.enabled=false

4.4.禁用 swagger-ui
要禁用 swagger-ui，请使用以下属性：

Disabling the swagger-ui

springdoc.swagger-ui.enabled=false

4.5. Swagger-ui 配置
该库支持 swagger-ui 官方属性：

https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/

您需要将 swagger-ui 属性声明为 spring-boot 属性。所有这些属性都应使用以下前缀声明：springdoc.swagger-ui

4.6.选择要包含在文档中的 Rest 控制器
此外，对于 swagger-annotations 中的 @Hidden 注释，可以使用包或路径配置来限制生成的 OpenAPI 描述。

对于要包含的包列表，请使用以下属性：

Packages to include

springdoc.packagesToScan=com.package1, com.package2

对于要包含的路径列表，请使用以下属性：

Paths to include

springdoc.pathsToMatch=/v1, /api/balance/**

4.7.带有功能端点的 Spring-webflux/WebMvc.fn
自 v1.5.0 版本以来，由于 spring 框架中的增强功能，引入了功能 DSL：#25938

它是注释的替代功能 API @RouterOperations。

这是一个示例 DSL，用于生成 webflux/WebMvc.fn REST 端点的 OpenAPI 描述：

@Bean
RouterFunction<?> routes() {
return route().GET(“/foo”, HANDLER_FUNCTION, ops -> ops
.operationId(“hello”)
.parameter(parameterBuilder().name(“key1”).description(“My key1 description”))
.parameter(parameterBuilder().name(“key2”).description(“My key2 description”))
.response(responseBuilder().responseCode(“200”).description(“This is normal response description”))
.response(responseBuilder().responseCode(“404”).description(“This is another response description”))
).build();
}

这是一些示例代码的链接：

你好路由器

行情路由器

图书路由器

员工路由器

位置路由器

以及使用功能端点 DSL 的演示代码：

使用功能 DSL 的示例 webflux 应用程序

从 版本开始v1.3.8，增加了功能端点的支持。为此添加了两个主要注释：@RouterOperations和@RouterOperation。

只有带@RouterOperations和的 REST API@RouterOperation才能显示在 swagger-ui 上。

@RouterOperation：如果 Router bean 包含与 REST API 相关的单个路由，则可以单独使用。使用 @RouterOperation 时，不强制填写路径

@RouterOperation，可以直接引用一个spring Bean（beanClass属性）和底层方法（beanMethod属性）：Springdoc-openapi，然后会检查这个方法以及这个方法级别的swagger注解。

@Bean
@RouterOperation(beanClass = EmployeeService.class, beanMethod = “findAllEmployees”)
RouterFunction getAllEmployeesRoute() {
return route(GET(“/employees”).and(accept(MediaType.APPLICATION_JSON)),
req -> ok().body(
employeeService().findAllEmployees(), Employee.class));
}

@RouterOperation，包含@Operation注释。@Operation如果声明了属性 beanMethod，则注释也可以放置在 bean 方法级别上。

不要忘记设置操作Id，这是强制性的。
@Bean
@RouterOperation(operation = @Operation(operationId = “findEmployeeById”, summary = “Find purchase order by ID”, tags = { “MyEmployee” },
parameters = { @Parameter(in = ParameterIn.PATH, name = “id”, description = “Employee Id”) },
responses = { @ApiResponse(responseCode = “200”, description = “successful operation”, content = @Content(schema = @Schema(implementation = Employee.class))),
@ApiResponse(responseCode = “400”, description = “Invalid Employee ID supplied”),
@ApiResponse(responseCode = “404”, description = “Employee not found”) }))
RouterFunction getEmployeeByIdRoute() {
return route(GET(“/employees/{id}”),
req -> ok().body(
employeeRepository().findEmployeeById(req.pathVariable(“id”)), Employee.class));
}

@RouterOperations：如果 Router bean 包含多个路由，则应使用此注释。使用 RouterOperations 时，必须填写路径属性。

A @RouterOperations、包含很多@RouterOperation。

@RouterOperations({ @RouterOperation(path = “/getAllPersons”, beanClass = PersonService.class, beanMethod = “getAll”),
@RouterOperation(path = “/getPerson/{id}”, beanClass = PersonService.class, beanMethod = “getById”),
@RouterOperation(path = “/createPerson”, beanClass = PersonService.class, beanMethod = “save”),
@RouterOperation(path = “/deletePerson/{id}”, beanClass = PersonService.class, beanMethod = “delete”) })
@Bean
public RouterFunction personRoute(PersonHandler handler) {
return RouterFunctions
.route(GET(“/getAllPersons”).and(accept(MediaType.APPLICATION_JSON)), handler::findAll)
.andRoute(GET(“/getPerson/{id}”).and(accept(MediaType.APPLICATION_STREAM_JSON)), handler::findById)
.andRoute(POST(“/createPerson”).and(accept(MediaType.APPLICATION_JSON)), handler::save)
.andRoute(DELETE(“/deletePerson/{id}”).and(accept(MediaType.APPLICATION_JSON)), handler::delete);
}

所有使用@RouterOperation填写的文档，都可能由router功能数据来完成。为此，@RouterOperation字段必须帮助唯一地识别相关路线。 使用以下标准springdoc-openpi扫描与注释相关的唯一路线：@RouterOperation

按路径

通过路径和RequestMethod

通过路径并产生

通过路径并消耗

通过路径和RequestMethod并产生

通过路径和RequestMethod并消耗

按路径生产和消费

通过路径和RequestMethod并生产和消费

GITHUB 上提供了一些代码示例演示：

带有功能端点文档的示例应用程序

以及一些项目测试：（从app69到app75）

带有功能端点文档的示例代码

4.8.与 WildFly 集成
对于 WildFly 用户，您需要添加以下依赖项才能使 swagger-ui 正常工作：