springdoc-openapi-starter-webmvc-ui

文档地址：https://springdoc.org/

https://blog.csdn.net/qq_55269149/article/details/137285469

一、简介

springdoc-openapi java 库有助于使用 Spring Boot 项目自动生成 API 文档。 springdoc-openapi 的工作原理是在运行时检查应用程序，根据 spring 配置、类结构和各种注释推断 API 语义。
自动生成 JSON/YAML 和 HTML 格式 API 文档。这些文档可以通过使用 swagger-api 注解 的注释来完成。

该库支持：

  • OpenAPI 3
  • Spring-boot v3（Java 17 和 Jakarta EE 9）
  • JSR-303，专门用于@NotNull、@Min、@Max 和@Size。
  • Swagger-ui
  • OAuth 2
  • GraalVM 原生镜像

文档：https://springdoc.org

注意：这是一个基于社区的项目，不由 Spring Framework Contributors (Pivotal) 维护。

springdoc-openapi v1.8.0 是支持 Spring Boot 2.x 和 1.x 的最新开源版本。

2. 快速入门

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

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

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

  • 文档将以 HTML 格式提供，使用官方 swagger-ui jar

  • 然后，Swagger UI 页面将在以下位置提供 http://server:port/context-path/swagger-ui.html ，并且 OpenAPI 描述将在以下 json 格式的 url 中提供：http://server:port/context-path/v3/api-docs

    • server：服务器名称或IP
    • port：服务器端口
    • context-path：应用程序的上下文路径

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

对于 HTML 格式的 swagger 文档的自定义路径，请在 spring-boot 配置文件中添加自定义 springdoc 属性：

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

3. Springdoc-openapi模块

3.1.总体概述

3.2. Spring WebMvc 支持

  • 以下 url 提供了 json 格式的文档：http://server:port/context-path/v3/api-docs
    • server：服务器名称或IP
    • port：服务器端口
    • context-path：应用程序的上下文路径
  • 文档也将以 yaml 格式提供，路径如下：/v3/api-docs.yaml

将库添加到项目依赖项列表中。 （无需额外配置）

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.5.0</version>
</dependency>

对于 Json 格式的 OpenAPI 文档的自定义路径，请在 spring-boot 配置文件中添加自定义 springdoc 属性：

# /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-starter-webflux-api</artifactId>
    <version>2.5.0</version>
</dependency>

3.4. Spring Hateoas 支持
使用依赖项 springdoc-openapi-hateoas 可以获得对 Spring Hateoas 的支持。

使用的项目spring-boot-starter-hateoas应该使用：

springdoc-openapi-starter-webmvc-api如果他们只需要访问 OpenAPI 端点

或者springdoc-openapi-starter-webmvc-ui，如果他们还需要访问 swagger-ui

3.5. Spring Data Rest 支持
springdoc-openapi项目支持spring-boot-starter-data-rest以下类型：@RepositoryRestResource和QuerydslPredicate注释。

使用的项目spring-boot-starter-data-rest应该使用：

springdoc-openapi-starter-webmvc-api如果他们只需要访问 OpenAPI 端点

或者springdoc-openapi-starter-webmvc-ui，如果他们还需要访问 swagger-ui

3.6. Spring 安全支持

springdoc-openapi如果在 REST 控制器上使用 @AuthenticationPrincipal 类型，则有助于忽略它。

springdoc-openapi还支持公开spring-security-oauth2-authorization-server.

spring-boot-starter-security使用或应该使用的项目spring-security-oauth2-authorization-server ：

springdoc-openapi-starter-webmvc-api如果他们依赖spring-boot-starter-web并且只需要访问 OpenAPI 端点。

或者springdoc-openapi-starter-webmvc-ui，如果他们依赖spring-boot-starter-web并且还需要访问 swagger-ui。

或者，springdoc-openapi-starter-webflux-api如果它们依赖于spring-boot-starter-webflux且仅访问 OpenAPI 端点。

或者springdoc-openapi-starter-webflux-ui，如果他们依赖spring-boot-starter-webflux并且还需要访问 swagger-ui。

3.7.执行器支持
为了显示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

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

例如，如果您有以下设置：

两个端点将可用：

保存 OpenAPI 定义的 REST API：

http://serverName:managementPort/actuator/openapi

一个端点，路由到 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-openapi属性均不适用springdoc.use-management-port=true。

如果您想从执行器基本路径下部署的 swagger-ui 到达应用程序端点，使用与应用程序不同的端口，CORS for your endpoints则应在应用程序级别启用。
此外，还可以将此属性与现有属性结合起来，以在 swagger-ui 中显示执行器端点。

springdoc.show-actuator=true

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

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

http://serverName:managementPort/actuator/swagger-ui

如果管理端口与应用程序端口不同且未springdoc.use-management-port定义但springdoc.show-actuator设置为 true：

然后可以通过应用程序端口访问 swagger-ui。例如：http://serverName:applicationPort/swagger-ui.html

默认情况下将添加执行器端点的专用组。

如果没有为应用程序定义组，则会添加一个默认组。

如果您想到达这种情况下的执行器端点（与应用程序不同的端口），CORS则应启用执行器端点。
注意：执行器基本路径下的这些新端点的命名目前无法自定义。

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

这些启动器将显示端点的 OpenAPI 描述spring-cloud-function-web。

如果您正在使用spring-web，只需添加springdoc-openapi-starter-webmvc-ui依赖项即可。

如果您正在使用spring-webflux，只需添加springdoc-openapi-starter-webflux-ui依赖项即可。

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

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

不要忘记设置操作Id，这是强制性的。
@Bean
@RouterOperation(operation = @Operation(description = “Say hello”, operationId = “hello”, tags = “persons”,
responses = @ApiResponse(responseCode = “200”, content = @Content(schema = @Schema(implementation = PersonDTO.class)))))
public Supplier helloSupplier() {
return () -> new PersonDTO();
}

@RouterOperations：该注解应用于描述 暴露的多个 REST API spring-cloud-function-web。使用时RouterOperations，必须填写方法属性。

A @RouterOperations、包含很多@RouterOperation。

@Bean
@RouterOperations({
@RouterOperation(method = RequestMethod.GET, operation = @Operation(description = “Say hello GET”, operationId = “lowercaseGET”, tags = “persons”)),
@RouterOperation(method = RequestMethod.POST, operation = @Operation(description = “Say hello POST”, operationId = “lowercasePOST”, tags = “positions”))
})
public Function<Flux, Flux> lowercase() {
return flux -> flux.map(value -> value.toLowerCase());
}

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

使用 Spring Cloud Function Web 的示例应用程序

3.9. Kotlin 支持
springdoc-openapi支持 Kotlin 类型。

使用的项目Kotlin应该使用：

springdoc-openapi-starter-webmvc-api如果他们依赖spring-boot-starter-web并且只需要访问 OpenAPI 端点。

或者springdoc-openapi-starter-webmvc-ui，如果他们依赖spring-boot-starter-web并且还需要访问 swagger-ui。

或者，springdoc-openapi-starter-webflux-api如果它们依赖于spring-boot-starter-webflux且仅访问 OpenAPI 端点。

或者springdoc-openapi-starter-webflux-ui，如果他们依赖spring-boot-starter-webflux并且还需要访问 swagger-ui。

此外，您的项目jackson-module-kotlin还应该添加以下类型的完整支持Kotlin：

com.fasterxml.jackson.module
jackson-module-kotlin

3.10. Groovy 支持
使用的项目Groovy应该使用：

springdoc-openapi-starter-webmvc-api如果他们依赖spring-boot-starter-web并且只需要访问 OpenAPI 端点。

或者springdoc-openapi-starter-webmvc-ui，如果他们依赖spring-boot-starter-web并且还需要访问 swagger-ui。

或者，springdoc-openapi-starter-webflux-api如果它们依赖于spring-boot-starter-webflux且仅访问 OpenAPI 端点。

或者springdoc-openapi-starter-webflux-ui，如果他们依赖spring-boot-starter-webflux并且还需要访问 swagger-ui。

3.11. Javadoc 支持
springdoc-openapi可以内省Javadoc注释和评论：

方法的javadoc注释：被解析为@Operation描述

@return : 被解析为@Operation响应描述

属性的 javadoc 注释：解析为该字段的“@Schema”描述。

需要支持的项目Javadoc应使用：

springdoc-openapi-starter-webmvc-api如果他们依赖spring-boot-starter-web并且只需要访问 OpenAPI 端点。

或者springdoc-openapi-starter-webmvc-ui，如果他们依赖spring-boot-starter-web并且还需要访问 swagger-ui。

或者，springdoc-openapi-starter-webflux-api如果它们依赖于spring-boot-starter-webflux且仅访问 OpenAPI 端点。

或者springdoc-openapi-starter-webflux-ui，如果他们依赖spring-boot-starter-webflux并且还需要访问 swagger-ui。

此外，您的项目应该添加therapi-runtime-javadoc在运行时读取 Javadoc 注释。确保将其及其注释处理器添加到项目的依赖项中。否则，Javadoc 支持将默默失败。




org.apache.maven.plugins
maven-compiler-plugin



com.github.therapi
therapi-runtime-javadoc-scribe
0.15.0





<!-- Runtime library -->
<dependency>
    <groupId>com.github.therapi</groupId>
    <artifactId>therapi-runtime-javadoc</artifactId>
    <version>0.15.0</version>
</dependency>

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

作者：Jeebiz  创建时间：2024-04-23 23:10
最后编辑：Jeebiz  更新时间：2024-10-05 00:01