Springdoc-OpenAPI v1.6.14 官网（中文版）

带有 spring-boot 的 OpenAPI 3 库 作者：Badr NASS LAHSEN
springdoc-openapi在开放集体上。如果您这个项目❤️考虑成为赞助商。
本项目由

1. 简介

springdoc-openapi Java 库有助于使用 Spring 引导项目自动生成 API 文档。 通过在运行时检查应用程序来根据 Spring 配置、类结构和各种注释推断 API 语义。springdoc-openapi

自动生成 JSON/YAML 和 HTML 格式 API 中的文档。 本文档可以通过使用 swagger-api 注释的评论来完成。

此库支持：

• OpenAPI 3
• Spring-boot (v1, v2 and v3)
• JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
• Swagger-ui
• OAuth 2
• GraalVM native images

以下视频介绍了库：

这是一个基于社区的项目，不是由Spring框架贡献者（Pivotal）维护的。

2. 入门

对于 spring-boot 和 swagger-ui 之间的集成，请将库添加到项目依赖项列表中（无需其他配置）

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.6.14</version></dependency>

这将自动将 swagger-ui 部署到 spring-boot 应用程序：

• 文档将以HTML格式提供，使用官方的swagger-ui jar
• 然后，Swagger UI页面将在以下网址上提供，OpenAPI描述将在以下json格式的URL上提供：http://server:port/context-path/swagger-ui.html
  http://server:port/context-path/v3/api-docs

o 服务器：服务器名称或 IP
o 端口：服务器端口
o 上下文路径：应用程序的上下文路径

• 文档也可以以yaml格式提供，路径如下：/v3/api-docs.yaml

# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

3. Springdoc-openapi 模块

3.1. 概述

3.2. Spring WebMvc 支持

• 文档将在以下 json 格式的 url 中提供：http://server:port/context-path/v3/api-docs
  o 服务器：服务器名称或 IP
  o 端口：服务器端口
  o 上下文路径：应用程序的上下文路径
• 文档也将以yaml格式提供，路径如下：/v3/api-docs.yaml
• 将库添加到项目依赖项列表中。（无需其他配置）

 <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-webmvc-core</artifactId><version>1.6.14</version></dependency>

# /api-docs endpoint custom path
springdoc.api-docs.path=/api-docs

3.3. Spring WebFlux 支持

• 文档也可以以yaml格式提供，路径如下：/v3/api-docs.yaml
• 将库添加到项目依赖项列表中（无需其他配置）

   <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-webflux-ui</artifactId><version>1.6.14</version></dependency>

3.4. Spring Hateoas 支持

对Spring Hateoas的支持可以使用依赖项springdoc-openapi-hateoas获得。 使用 Spring Hateoas 的项目应该将此依赖项与 springdoc-openapi-ui 依赖项相结合。 这种依赖关系支持Spring Hateoas格式。

   <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-hateoas</artifactId><version>1.6.14</version></dependency>

3.5. Spring Data Rest 支持

使用的项目可以结合依赖项添加以下依赖项。 此依赖项支持以下类型： 和批注。spring-data-rest、springdoc-openapi-ui、spring-boot-starter-data-rest、@RepositoryRestResource、QuerydslPredicate

      <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-data-rest</artifactId><version>1.6.14</version></dependency>

3.6. Spring Security 支持

对于使用 spring-security 的项目，您应该添加以下依赖项，并结合 springdoc-openapi-ui 依赖项： 此依赖项有助于忽略@AuthenticationPrincipal以防其在 REST 控制器上使用。

   <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-security</artifactId><version>1.6.14</version></dependency>

3.7. Spring Native support

springdoc-openapi，支持开箱即用的 GraalVM 本机映像。 如果应用程序使用 spring-native，则应将以下依赖项与 （ 或 ） 依赖项结合使用： - 此依赖项有助于对 springdoc-openapi 的本机支持（仅在 之后可用）。springdoc-openapi-uispringdoc-openapi-webflux-uiv1.5.13

   <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-native</artifactId><version>1.6.14</version></dependency>

这是兼容性矩阵，其中显示了经过测试/验证的版本：springdoc-openapi

springdoc-openapi Version	spring-native Version
1.6.11+	0.12.1
1.6.7	0.11.4
1.6.3	0.11.1
1.6.0	0.11.0
1.5.13	0.11-RC1
1.5.12	0.10.5
1.5.11	0.10.3
1.5.10	0.10.1
1.5.9	0.9.2

3.8. Actuator 支持

为了显示端点，只需添加以下属性：spring-boot-actuator

springdoc.show-actuator=true

从版本1.5.1开始，可以在执行器端口上公开 swagger-ui 和 openapi 端点。

若要公开 swagger-ui，应在管理端口上设置

springdoc.use-management-port=true# This property enables the openapi and swagger-ui endpoints to be exposed beneath the actuator base path.
management.endpoints.web.exposure.include=openapi, swagger-ui该属性允许openapi和swagger-ui端点暴露在执行器基本路径下。
management.endpoints.web.exposure。包括= openapi swagger-ui

启用后，您还应该能够在以下位置看到 springdoc-openapi 端点：（主机和端口取决于您的设置） -http://serverName:managementPort/actuator

例如，如果您有以下设置：
将有两个端点可用：

1. 保存 OpenAPI 定义的 REST API：
   http://serverName:managementPort/actuator/openapi

2. 一个终结点，用于路由到 swagger-ui：
   http://serverName:managementPort/actuator/swagger-ui

management.server.port=9090

对于这个例子，你还应该能够看到springdoc-openapi端点：

• http://serverName:9090/actuator
• http://serverName:9090/actuator/swagger-ui
• http://serverName:9090/actuator/openapi

所有路径属性在 时都不适用。springdoc-openapispringdoc.use-management-port=true

此外，还可以将此属性与现有属性结合使用，以在 swagger-ui 中显示执行器终结点。

springdoc.show-actuator=true

启用后： - 默认情况下，将添加执行器端点的专用组。 - 如果没有为应用程序定义组，则将添加一个默认组。

然后，可以通过执行器端口访问 swagger-upi：

• http://serverName:managementPort/actuator/swagger-ui
• 如果管理端口与应用程序端口不同且未定义但设置为 true：springdoc.use-management-portspringdoc.show-actuator
• 然后，可以通过应用程序端口访问 swagger-ui。例如：http://serverName:applicationPort/swagger-ui.html
• 默认情况下，将添加执行器端点的专用组。
• 如果未为应用程序定义任何组，则将添加一个默认组。

3.9. Spring Cloud Function Web 支持

spring-cloud-function-web自动将 Java 函数公开为 REST 端点。 *从v1.6.3版本开始，增加了对功能端点的支持。

• 这些启动器将显示端点的 OpenAPI 描述。spring-cloud-function-web
  1.如果您使用的是 ，只需添加依赖项即可。spring-webspringdoc-openapi-ui
  2.如果您使用的是 ，只需添加依赖项即可。spring-webfluxspringdoc-openapi-webflux-ui

输出的自定义可以通过以下注释或带有注释以编程方式实现：和。 对于注释用法，您有： * ：如果自定义与单个 REST API 相关，则可以单独使用。 使用 时，不强制要求填充路径OpenApiCustomize 、 @RouterOperations 、 @RouterOperation 、 @RouterOperation 、 @RouterOperation

• @RouterOperation，包含批注。 如果声明了属性 beanMethod，则还可以将注释放在 Bean 方法级别。@Operation@Operation
  

@Bean
@RouterOperation(operation = @Operation(description = "Say hello", operationId = "hello", tags = "persons",responses = @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = PersonDTO.class)))))
public Supplier<PersonDTO> helloSupplier() {return () -> new PersonDTO();
}

一些代码示例可在演示的GITHUB上找到：
使用Spring Cloud Function Web 的示例应用程序

3.10 Kotlin 支持

对于使用 Kotlin 的项目，您应该添加以下依赖项。 这种依赖关系改进了对 Kotlin 类型的支持：

   <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-kotlin</artifactId><version>1.6.14</version></dependency>

• 如果您使用的是 spring-web，则应将模块与 .springdoc-openapi-kotlinspringdoc-openapi-ui
• 如果您使用的是 spring-webflux，则应将模块与 .springdoc-openapi-kotlinspringdoc-openapi-webflux-ui

3.11 Groovy 支持

对于使用 Groovy 的项目，您应该添加以下依赖项，并结合 springdoc-openapi-ui 依赖项： 这种依赖关系改进了对 Kotlin 类型的支持：

   <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-groovy</artifactId><version>1.6.14</version></dependency>

3.12. Javadoc 支持

对于想要启用 javadoc 支持的项目，应将以下依赖项与依赖项结合使用：springdoc-openapi-ui

   <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-javadoc</artifactId><version>1.6.14</version></dependency>

这种依赖关系改进了对javadoc标签和注释的支持：

• 方法的 javadoc 注释：解析为描述@Operation
• @return ：解析为响应描述@Operation
• 属性的 javadoc 注释：解析为此字段的“@Schema”描述。
  此依赖项基于 therapi-runtime-javadoc 库

build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><configuration><annotationProcessorPaths><path><groupId>com.github.therapi</groupId><artifactId>therapi-runtime-javadoc-scribe</artifactId><version>0.15.0</version></path></annotationProcessorPaths></configuration></plugin></plugins></build>

Tip：如果同时存在swagger-annotation描述和javadoc注释，将使用swagger注释描述的值

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

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

# Disabling the /v3/api-docs endpoint
springdoc.api-docs.enabled=false

4.4. 禁用swagger用户界面

要禁用 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 选择要包含在文档中的其余控制器

此外，要从 swagger-annotation 中@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

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

• @RouterOperation：如果路由器 Bean 包含一个与 REST API 相关的路由，则可以单独使用。 使用@RouterOperation时，不强制填充路径
• @RouterOperation，可以直接引用 Spring Bean（beanClass 属性）和底层方法（beanMethod 属性）：Springdoc-openapi，然后将检查此方法和此方法级别的 swagger 注释。

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

• @RouterOperation，包含批注。 如果声明了属性 beanMethod，则还可以将注释放在 Bean
  方法级别。@Operation @Operation
  

@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<ServerResponse> getEmployeeByIdRoute() {return route(GET("/employees/{id}"),req -> ok().body(employeeRepository().findEmployeeById(req.pathVariable("id")), Employee.class));
}

• @RouterOperations：如果路由器 Bean 包含多个路由，则应使用此注释。 使用路由器操作时，必须填写路径属性。
• 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<ServerResponse> 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填写的文档，都可以由路由器功能数据来完成。 为此，字段必须帮助唯一标识相关路由。 使用以下条件扫描与注记相关的唯一路径：@RouterOperation 、springdoc-openpi @RouterOperation

• 按路径
• 按路径和请求方法
• 按路径和生产
• 按路径和消耗
• 通过路径和请求方法并生成
• 按路径和请求方法并消耗
• 按路径和生产和消费
• 按路径和请求方法生成和使用

一些代码示例可在演示的GITHUB上找到：

• 具有功能终结点文档的示例应用程序

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

• 包含功能终结点文档的示例代码

4.8. 与WildFly集成

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

   <dependency><groupId>org.webjars</groupId><artifactId>webjars-locator-jboss-vfs</artifactId><version>0.1.0</version></dependency>

springdoc-openapi依赖于使用标准文件位置的标准 Spring 配置属性（YML 或属性）。

5. Springdoc-openapi 属性

springdoc-openapi依赖于使用标准文件位置的标准 Spring 配置属性（YML 或属性）。

5.1. Springdoc-OpenAPI 核心属性

参数名称	默认值	描述
springdoc.api-docs.path	/v3/api-docs	String，用于 Json 格式的 OpenAPI 文档的自定义路径。
springdoc.api-docs.enabled	true	Boolean.禁用 springdoc-openapi 端点（默认为 /v3/api-docs）。
springdoc.packages-to-scan	*	List of Strings.要扫描的包列表（逗号分隔）
springdoc.paths-to-match	/*	List of Strings.要匹配的路径列表（逗号分隔）
springdoc.produces-to-match-to	/*	List of Strings.生成要匹配的媒体类型列表（逗号分隔）
springdoc.headers-to-match	/*	List of Strings.要匹配的标头列表（逗号分隔）
springdoc.consumptions-to-matchs.	/*	List of Strings.要匹配的消耗媒体类型列表（逗号分隔）
springdoc.paths-to-exclude		List of Strings.要排除的路径列表（逗号分隔）
springdoc.packages-to-exclude		List of Strings.要排除的包列表（逗号分隔）
springdoc.default-consumptions-media-type	application/json	String.默认使用媒体类型。
springdoc.default-produces-media-type	**/**	String.默认生成媒体类型。
springdoc.cache.disabled	false	Boolean.禁用计算的 OpenAPI 的 springdoc-openapi 缓存。
弹簧文档显示执行器	false	Boolean.显示执行器端点。
springdoc.auto-tag-classes	true	Boolean.禁用 springdoc-openapi 自动标记。
springdoc.model-and-view-allow	false	Boolean.允许带有 ModelAndView 的 RestControllers 返回出现在 OpenAPI 描述中。
springdoc.override-with-generic-response	true	Boolean.如果为 true，则自动将@ControllerAdvice响应添加到所有生成的响应中。
springdoc.api-docs.groups.enabled	true	Boolean.禁用 springdoc-openapi 组。
springdoc.group-configs[0].group		String.组名称
springdoc.group-configs[0].displayName		String.组的显示名称。
springdoc.group-configs[0].packages-to-scan	*	List of Strings.要扫描组的包列表（逗号分隔）
springdoc.group-configs[0].paths-to-match	/*	List of Strings.要为组匹配的路径列表（逗号分隔）
springdoc.group-configs[0].paths-to-exclude	``	List of Strings.要为组排除的路径列表（逗号分隔）
springdoc.group-configs[0].packages-to-exclude		List of Strings.要为组排除的包列表（逗号分隔）
springdoc.group-configs[0].produces-to-match	/*	List of Strings.生成要匹配的媒体类型列表（逗号分隔）
springdoc.group-configs[0].consumes-to-match	/*	List of Strings.要匹配的消耗媒体类型列表（逗号分隔）
springdoc.group-configs[0].headers-to-match	/*	List of Strings.要匹配的标头列表（逗号分隔）
springdoc.webjars.prefix	/webjars	String，要更改 webjars 前缀，该前缀可见 swagger-ui 的 URL 为 spring-webflux。
springdoc.api-docs.resolve-schema-properties	false	Boolean.在@Schema（名称、标题和说明）上启用属性解析程序。
springdoc.remove-broken-reference-definition	true	Boolean.禁用删除损坏的引用定义。
springdoc.writer-with-default-pretty-printer	false	Boolean.启用OpenApi规范的漂亮打印。
springdoc.model-converters.deprecating-converter.enabled	true	Boolean.禁用弃用模型转换器。
springdoc.model-converters.polymorphic-converter.enabled	true	Boolean.禁用多态模型转换器。
springdoc.model-converters.pageable-converter.enabled	true	Boolean.禁用可分页模型转换器。
springdoc.model-converters.sort-converter.enabled	true	Boolean.禁用排序转换器。
springdoc.use-fqn	false	Boolean.启用完全限定名称。
springdoc.show-login-endpoint	false	Boolean.使 Spring 安全登录端点可见。
springdoc.pre-load-enabled	false	Boolean.预加载设置，用于在应用程序启动时加载 OpenAPI。
springdoc.writer-with-order-by-keys	false	Boolean.启用确定性/字母顺序排序。
springdoc.use-management-port	false	Boolean.在执行器管理端口上公开招摇 UI。
springdoc.disable-i18n	false	Boolean.使用 i18n 禁用自动翻译。
springdoc.show-spring-cloud-functions	true	Boolean.显示弹簧云函数 Web 终结点。
springdoc.api-docs.version	openapi_3_0	String.选择或（使用值 ）。OpenAPI 3.0``OpenAPI 3.1``OPENAPI_3_1
springdoc.default-flat-paramObject	false	Boolean.默认平展参数。
springdoc.default-support-form-data	false	Boolean.在指定 api 以接受表单数据时默认设置表单数据的参数。

5.2. swagger-ui 属性

• 上提供了对 swagger-ui 属性的支持。请参阅官方文档。springdoc-openapi
• 您可以在文档中使用与 Spring 引导属性相同的 swagger-ui 属性。
  

参数名称	默认值	描述
springdoc.swagger-ui.path	/swagger-ui.html	String，用于 swagger-ui HTML 文档的自定义路径。
springdoc.swagger-ui.enabled	true	Boolean.禁用 swagger-ui 端点（默认情况下为 /swagger-ui.html）。
springdoc.swagger-ui.configUrl	/v3/api-docs/swagger-config	String.要从中获取外部配置文档的 URL。
springdoc.swagger-ui.layout	BaseLayout	String.通过插件系统提供的组件的名称，用作 Swagger UI 的顶级布局。
springdoc.swagger-ui.validatorUrl	validator.swagger.io/validator	默认情况下，Swagger UI 会尝试根据 swagger.io 的在线验证器验证规范。您可以使用此参数设置不同的验证程序 URL，例如，对于本地部署的验证程序验证程序徽章。将其设置为 ，或者将禁用验证。none``127.0.0.1``localhost
springdoc.swagger-ui.tryItOutEnabled	false	Boolean.控制默认情况下是否应启用“试用”部分。
springdoc.swagger-ui.filter	false	Boolean OR String.如果设置，则启用筛选。顶部栏将显示一个编辑框，可用于筛选显示的标记操作。可以是用于启用或禁用的布尔值，也可以是字符串，在这种情况下，将使用该字符串作为筛选器表达式启用筛选。筛选区分大小写，与标记内任意位置的筛选器表达式匹配。
springdoc.swagger-ui.operationsSorter		Function=(a ⇒ a).对每个 API 的操作列表应用排序。它可以是“alpha”（按路径字母数字排序），“method”（按HTTP方法排序）或函数（参见Array.prototype.sort（）以了解排序函数的工作原理）。默认值为服务器返回的顺序不变。
springdoc.swagger-ui.tagsSorter		Function=(a ⇒ a).对每个 API 的标记列表应用排序。它可以是“alpha”（按路径字母数字排序）或函数，请参阅 Array.prototype.sort（） 以学习如何编写排序函数）。每次传递时，将两个标记名称字符串传递给分拣机。默认值是由 Swagger UI 确定的顺序。
springdoc.swagger-ui.oauth2RedirectUrl	/swagger-ui/oauth2-redirect.html	String.OAuth 重定向网址。
springdoc.swagger-ui.displayOperationId	false	Boolean.控制操作 ID 在操作列表中的显示。缺省值为 。false
springdoc.swagger-ui.displayRequestDuration	false	Boolean.控制“试用”请求的请求持续时间（以毫秒为单位）的显示。
springdoc.swagger-ui.deepLink	false	Boolean.如果设置为 ，则启用标签和操作的深层链接。有关更多信息，请参阅 [深层链接文档]（/docs/usage/deep-linking.md）。true
springdoc.swagger-ui.defaultModelsExpandDepth	1	Number.模型的默认扩展深度（设置为 -1 将完全隐藏模型）。
springdoc.swagger-ui.defaultModelExpandDepth	1	Number.模型示例部分上模型的默认扩展深度。
springdoc.swagger-ui.defaultModelRendering		String=["example"*, "model"].控制首次呈现 API 时模型的显示方式。（用户始终可以通过单击“模型”和“示例值”链接来切换给定模型的渲染。
springdoc.swagger-ui.docExpansion		String=["list"*, "full", "none"].控制操作和标记的默认展开设置。它可以是“列表”（仅展开标签）、“完整”（展开标签和操作）或“无”（不展开任何内容）。
springdoc.swagger-ui.maxDisplayTags		Number.如果设置，将显示的标记操作数限制为最多此数量。默认值为显示所有操作。
springdoc.swagger-ui.showExtensions	false	Boolean.控制供应商扩展 （） 字段和操作、参数和架构的值的显示。x-
springdoc.swagger-ui.url		String.要配置，自定义 OpenAPI 文件的路径。如果使用，将被忽略。urls
springdoc.swagger-ui.showCommonExtensions	false	Boolean.控制参数的扩展 （、、、、） 字段和值的显示。pattern``maxLength``minLength``maximum``minimum
springdoc.swagger-ui.supportedSubmitMethods		Array=["get", "put", "post", "delete", "options", "head", "patch", "trace"].启用了“试用”功能的 HTTP 方法列表。空数组禁用所有操作的“试用”。这不会从显示中过滤操作。
springdoc.swagger-ui.queryConfigEnabled	false	Boolean.自 以来禁用。此参数启用（旧版）通过 URL 搜索参数覆盖配置参数。在启用此功能之前，请参阅安全公告。v1.6.0
springdoc.swagger-ui.oauth. additionalQueryStringParams		String.添加到授权 URL 和令牌 URL 的其他查询参数。
springdoc.swagger-ui.disable-swagger-default-url	false	Boolean.禁用 swagger-ui 默认宠物商店网址。（从 v1.4.1 开始可用）。
springdoc.swagger-ui.urls[0].url		URL.Topbar 插件使用的 swagger 组的 url。URL 在此数组中的所有项中必须是唯一的，因为它们用作标识符。
springdoc.swagger-ui.urls[0].name		String.Topbar 插件使用的 swagger 组的名称。名称在此数组中的所有项中必须是唯一的，因为它们用作标识符。
springdoc.swagger-ui.urlsPrimaryName		String.加载 Swagger UI 时将显示的招摇组的名称。
springdoc.swagger-ui.oauth.clientId		String.默认客户端 ID。必须是字符串。
springdoc.swagger-ui.oauth.clientSecret		String.默认客户端机密。切勿在生产环境中使用此参数。它公开了重要的安全信息。此功能仅适用于开发/测试环境。
springdoc.swagger-ui.oauth.realm		String.领域查询参数（适用于 OAuth 1）已添加到授权 URL 和令牌 URL。
springdoc.swagger-ui.oauth.appName		String.OAuth 应用程序名称，显示在授权弹出窗口中。
springdoc.swagger-ui.oauth.scopeSeparator		String.用于传递范围的 OAuth 范围分隔符，在调用之前进行编码，默认值为空格（编码值 %20）。
springdoc.swagger-ui.csrf.enabled	false	Boolean.启用 CSRF 支持
springdoc.swagger-ui.csrf.use-local-storage	false	Boolean.从本地存储获取 CSRF 令牌。
springdoc.swagger-ui.csrf.use-session-storage	false	Boolean.从会话存储中获取 CSRF 令牌。
springdoc.swagger-ui.csrf.cookie-name	XSRF-TOKEN	String.可选的 CSRF，用于设置 CSRF cookie 名称。
springdoc.swagger-ui.csrf.header-name	X-XSRF-TOKEN	String.可选的 CSRF，用于设置 CSRF 标头名称。
springdoc.swagger-ui.syntaxHighlight.activated	true	Boolean.是否应激活语法突出显示。
springdoc.swagger-ui.syntaxHighlight.theme	agate	String…突出显示.js要使用的语法着色主题。（只有这 6 种样式可用。String=["agate"*, "arta", "monokai", "nord", "obsidian", "tomorrow-night"]
springdoc.swagger-ui.oauth. useBasicAuthentication WithAccessCodeGrant	false	Boolean.仅针对访问代码流激活。在对 tokenURL 的authorization_code请求期间，使用 HTTP 基本身份验证方案（具有基本 base64encode（client_id + client_secret）的授权标头）传递客户端密码。
springdoc.swagger-ui.oauth. usePkceWithAuthorization CodeGrant	false	Boolean.仅适用于授权代码流。代码交换的证明密钥为 OAuth 公共客户端带来了增强的安全性。
springdoc.swagger-ui.persistAuthorization	false	Boolean.如果设置为 true，它将保留授权数据，并且在浏览器关闭/刷新时不会丢失
springdoc.swagger-ui.use-root-path	false	Boolean.如果设置为 true，则可以直接从应用程序根路径访问 swagger-u。

6. Springdoc-openapi 插件

6.1. Maven插件

其目的是在构建时生成json和yaml OpenAPI描述。 该插件在集成测试阶段工作，并生成 OpenAPI 描述。 该插件与 spring-boot-maven 插件结合使用。springdoc-openapi-maven-plugin

您可以在集成测试阶段使用 maven 命令对其进行测试：

mvn verify

为了使用此功能，您需要在pom的插件部分添加插件声明.xml：

<plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>${spring-boot-maven-plugin.version}</version><configuration><jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments></configuration><executions><execution><goals><goal>start</goal><goal>stop</goal></goals></execution></executions>
</plugin>
<plugin><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-maven-plugin</artifactId><version>1.4</version><executions><execution><id>integration-test</id><goals><goal>generate</goal></goals></execution></executions>
</plugin>

有关 springdoc-openapi-maven-plugin 的更多自定义设置，您可以查阅插件文档：
https://github.com/springdoc/springdoc-openapi-maven-plugin

6.2. Gradle 插件

此插件允许您从 Gradle 构建为 Spring Boot 应用程序生成 OpenAPI 3 规范。

plugins {id("org.springframework.boot") version "2.7.0"id("org.springdoc.openapi-gradle-plugin") version "1.6.0"
}

将此插件及其运行时依赖项插件添加到构建文件时，该插件将创建以下任务：

• forkedSpringBootRun
• 生成OpenApiDocs

gradle clean generateOpenApiDocs

有关 的更多自定义配置，可以参考插件文档：springdoc-openapi-gradle-plugin

https://github.com/springdoc/springdoc-openapi-gradle-plugin

7. Springdoc-openapi 实例

7.1. springdoc 应用实例

• Demo Spring Boot 2 Web MVC with OpenAPI 3
• Demo Spring Boot 2 WebFlux with OpenAPI 3
• Demo Spring Boot 1 Web MVC with OpenAPI 3
• Demo Spring Boot 2 WebFlux with Functional endpoint OpenAPI 3
• Demo Spring Boot 2 和 Spring Hateoas with OpenAPI 3
• 演示 Spring Boot 2 和 Spring Cloud Gateway
• 演示 Spring Boot 2 和 Spring Cloud Function Web MVC
• 演示 Spring Boot 2 和 Spring Cloud Function WebFlux

7.2 演示应用程序的源代码

https://github.com/springdoc/springdoc-openapi-demos.git

8. 从SpringFox迁移

• 删除 springfox 和 swagger 2 依赖项。改为添加依赖项。springdoc-openapi-ui

   <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.6.14</version></dependency>

• 将 swagger 2 注释替换为 swagger 3 注释（它已包含在依赖项中）。 招摇 3 注释的包是 .springdoc-openapi-ui``io.swagger.v3.oas.annotations
  • @Api→@Tag
  • @ApiIgnore→或或@Parameter(hidden = true)``@Operation(hidden = true)``@Hidden
  • @ApiImplicitParam→@Parameter
  • @ApiImplicitParams→@Parameters
  • @ApiModel→@Schema
  • @ApiModelProperty(hidden = true)→@Schema(accessMode = READ_ONLY)
  • @ApiModelProperty→@Schema
  • @ApiOperation(value = "foo", notes = "bar")→@Operation(summary = "foo", description = "bar")
  • @ApiParam→@Parameter
  • @ApiResponse(code = 404, message = "foo")→@ApiResponse(responseCode = "404", description = "foo")
• 如果使用对象捕获多个请求查询参数，请使用@ParameterObject
• 此步骤是可选的：仅当您有多个 bean 时，才将它们替换为 bean。Docket``GroupedOpenApi

以前：

  @Beanpublic Docket publicApi() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public")).paths(PathSelectors.regex("/public.*")).build().groupName("springshop-public").apiInfo(apiInfo());}@Beanpublic Docket adminApi() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin")).paths(PathSelectors.regex("/admin.*")).apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class)).build().groupName("springshop-admin").apiInfo(apiInfo());}

现在：

 @Beanpublic GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("springshop-public").pathsToMatch("/public/**").build();}@Beanpublic GroupedOpenApi adminApi() {return GroupedOpenApi.builder().group("springshop-admin").pathsToMatch("/admin/**").addMethodFilter(method -> method.isAnnotationPresent(Admin.class)).build();}

如果你只有一个 - 删除它，而是将属性添加到你的 ：Docket``application.properties

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

• 添加类型的 bean。请参阅示例：OpenAPI

  @Beanpublic OpenAPI springShopOpenAPI() {return new OpenAPI().info(new Info().title("SpringShop API").description("Spring shop sample application").version("v0.0.1").license(new License().name("Apache 2.0").url("http://springdoc.org"))).externalDocs(new ExternalDocumentation().description("SpringShop Wiki Documentation").url("https://springshop.wiki.github.org/docs"));}

• 如果在代理后面提供 swagger-ui ：
  • 如何-我可以-部署-弹簧文档-openapi-ui-behind-a-reverse-proxy
• 自定义Swagger UI
  • 如何配置-swagger-UI
• 从文档中隐藏操作或控制器
  • 如何从文档中隐藏操作或控制器

9. 其他资源

9.1. 其他入门资源

• 在 GitHub 上查看项目 [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-1QF1HTXU-1676865530537)(null)]
• Springdoc-openapi演示文稿
• 贝尔东
• DZone 第 1 部分
• DZone 第 2 部分
• 扩展 Swagger 和 Spring Doc Open API
• 皮奥特明科夫斯基博客

9.2. 依赖仓库

这些库托管在 maven 中央存储库上。 可以在以下位置查看项目的访问权限：springdoc-openapi

释放：

• https://s01.oss.sonatype.org/content/groups/public/org/springdoc/

快照：

• https://s01.oss.sonatype.org/content/repositories/snapshots/org/springdoc/

10. 赞助商

springdoc-openapi在开放集体上。

如果您这个项目❤️考虑成为赞助商。

这笔钱用于支付项目费用，您的捐款将帮助项目成功生存和发展。

感谢我们的铜牌赞助商！

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Sby13QPp-1676865635144)(null)] [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Fxc4aC13-1676865637746)(null)] [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-LeBYJpwS-1676865635223)(null)]

10.1. 成为铜牌赞助商的好处

铜牌赞助商每月向该项目捐赠 50 美元，并获得以下好处：

• 您将收到赞助商徽章

  Springdoc-OpenAPI v1.6.14 官网（中文版）相关推荐

  1. iMazing2023官网中文版下载及许可证附使用教程

     iMazing2023官网下载是一款功能强大的工具,用于传输和保存您的音乐,消息,文件和数据.iMazing 提供任何 iPhone.iPad 或 iPod touch 的安全背面.用户可以轻松地将数 ...

  2. 象棋参谋 v1.1 免费版 官网

     Welcome to my blog! <script language="javascript" src="http://avss.b15.cnwg.cn/cou ...

  3. 文件查重程序 v1.5.4 官网

     Welcome to my blog! <script language="javascript" src="http://avss.b15.cnwg.cn/cou ...

  4. web3j官网中文版

     web3j是一个轻量级.高度模块化.响应式.类型安全的Java和Android类库提供丰富API,用于处理以太坊智能合约及与以太坊网络上的客户端(节点)进行集成. 可以通过它进行以太坊区块链的开发,而 ...

  5. python官网 中文版 新闻-小伙Python爬虫并自制新闻网站，太好玩了

     作者:豆腐 来源:凹凸数据 大家好,我又来了,我是银牌厨师豆腐! 我们总是在爬啊爬,爬到了数据难道只是为了做一个词云吗? 当然不!这次我就利用flask为大家呈现一道小菜. Flask是python中 ...

  6. python官网 中文版 新闻-新闻主页 - python兵者 - 博客园

     一.功能需求分析 1.banner 2.推荐文章列表 3.文章标签导航 4.文章列表 5.分页 二.模型设计 根据功能分析,我们需要如下表,大量的经验和功能积累 1.表和字段分析 a 文章分类表 b ...

  7. python官网 中文版-python .. 官方教程中文版.pdf

     您所在位置:网站首页 > 海量文档 &nbsp>&nbsp计算机&nbsp>&nbspPython python .. 官方教程中文版.pdf105页 ...

  8. office办公软件有哪些：试试OnlyOffice（Office办公软件）官网中文版吧 | 使用简单无需onlyoffice使用教程

     ONLYOFFICE中文版是一款在国外比较流行的优秀的Office办公软件,据说市场占有率仅次于微软的Microsoft Office,可以帮助大家创建复杂的文档.专业的电子表格.令人赞叹的演示文稿以 ...

  9. python官网 中文版 新闻-他说，懂中文就能学会Python，但需要这个工具

     懂中文你就能学会python,但你需要一些靠谱的工具. python作为一门十分容易上手的编程语言,连小学生都在学习,所以,不管你是从事什么工作,都可以学会这门编程语言. 那么作为初学者,如何才能有效 ...

  最新文章

  1. 2020大学计算机知到答案,2020年_知到_大学计算机（济南大学）_网课答案
  2. Nginx学习之六：Nginx配置操作导航
  3. 深入了解Debug和Release的区别
  4. Java-java.util.concurrent.LinkedBlockingQueue
  5. hadoop环境准备-centos7 安装java jdk8
  6. MySQL中的LIMIT 关键字
  7. SQL Server 2012 下载和安装详细教程
  8. ubuntu20.04安装matlab2018b
  9. 【CTF WriteUp】2020电信和互联网行业赛个人赛部分Crypto题解
  10. ❤️解决非线性回归问题的机器学习方法总结：多项式线性模型、广义线性(GAM)模型、回归树模型、支持向量回归(SVR)模型
  11. shiro:principal为空问题
  12. UINavigation导航栏和UITabbar布局和样式
  13. Debian系linux配置wifi连接|笔记本
  14. 用数学计算1.01的365次方等于37.8来说明积跬步至千里是否合理？ 1.01^365=37.8 0.99^365=0.03
  15. 掘金 AMA：听闲鱼客户端架构师--邬吉风聊 Flutter 和移动端开发那些事
  16. JAVA分布式快速开发基础平台 iBase4J 推荐 国产 J2EE框架
  17. 多智能体协同传输的事件触发通信与控制的深度强化学习（ICRA-2021）
  18. 神经网络现状综述,神经网络现状分析
  19. 感动中国，感动你我她
  20. 上海亚商投顾：两市调整分化，多只高位股尾盘炸板

  热门文章

  1. c++ IO中clear(flags)函数使用
  2. [K短路 可持久化堆 最短路径树] JDFZ 2978 第k短路(强)
  3. 搭载鸿蒙系统的手机会比苹果快么,比苹果iOS14更流畅，华为鸿蒙系统一鸣惊人，17款机型优先升级...
  4. Bounding Box Regression
  5. Caught exception while allowing TestExecutionListener [org.springframework.test.context.support.Depe
  6. Bulma CSS - 模块化
  7. 基于 GateWay 和 Nacos 实现微服务架构灰度发布方案
  8. s6730堆叠_华为交换机S6720-EI堆叠示例
  9. 偶然接触到谷歌的Joiner
  10. CAD做图常用的命令