有没有支持 OpenAPI 3.0 的 Spring Boot with Jersey 框架？

Question

有大量关于 Spring Boot、JAX-RS 和 Swagger 的教程。然而，他们中的大多数似乎都使用 OpenAPI 2 规范。我只找到了一篇使用 Spring、JAX-RS 和 OpenAPI 3.0 的教程（该教程使用了 Apache CXF）。

https://dzone.com/articles/moving-with-the-times-towards-openapi-v300-adoptio

其他 Spring Boot + JAX-RS 实现是否可以与 OpenAPI 3.0 配合使用？例如，所有关于 Jersey 的教程似乎都只输出 OpenAPI 2.0。Apache CXF 适合我正在做的事情，但我想知道是否有其他选择。

Springdoc-openapi 支持 spring boot 和 OpenAPI 3.0，不确定 jaxrs。 https://github.com/springdoc/springdoc-openapi

Answer 1

使用 JAX-RS 配置 Spring Boot 生成 OpenAPI 3.0 规范

您可以通过执行以下操作，使用Swagger与Spring Boot和JAX-RS一起生成OpenAPI 3.0 ：

1. 包括spring-boot-starter-jersey, swagger-core,swagger-annotations和swagger-jaxrs在pom.xml
2. 扩展ResourceConfig和配置包以扫描JAX - RS注释并注册OpenAPIResource.classSwagger 。
3. 使用 Swagger Annotations 来注释您的端点和架构。
4. sprindoc-openapi-ui如果您想通过访问Swagger ，则可以选择包含/swagger-ui.html。

1）pom.xml中的依赖关系

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-jersey</artifactId>
    </dependency>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-core</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>${swagger.version}</version>
        <exclusions>
            <exclusion>
                <groupId>io.github.classgraph</groupId>
                <artifactId>classgraph</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.2.18</version>
    </dependency>

当前swagger-version是2.1.0.

springdoc-openapi-ui与和存在冲突swagger-jaxrs2，这会导致 与 发生错误io.github.classgraph，因此必须从 中排除该库swagger-jaxrs2。

2：扩展ResourceConfig

@Component
@ApplicationPath("/api")
@Path("/")
public class JaxRsConfig extends ResourceConfig {
    public JaxRsConfig() {
        // register resources
        packages("com.example.jaxrs.resources");
        register(OpenApiResource.class);
    }
}

必须通过调用 来扫描 JAX-RS 带注释的资源packages("com.example.jaxrs.resources")。

注意，不要与 register 函数混淆！

来自OpenApiResource.classSwagger并提供端点/openapi.json。

/api我使用as的原因@ApplicationPath是，与 一起使用时springdoc-openapi-ui，设置为“/”swagger-ui.html时找不到端点@ApplicationPath。在这种情况下，似乎有些东西被覆盖了。也许有人对此有解释。

3）Swagger注释

@Schema(name = "Message", description = "This is an object to place a message.")
public class MessageDto {

    @Schema(name="Message", required = true)
    private String message;

    public MessageDto(String message) {
        super();
        this.message = message;
    }
    // ... getters and setters
}

4）配置SpringDoc

默认情况下，您应该能够调用/swagger-ui.html打开Swagger并浏览您的OpenAPI 3.0定义。

由于@ApplicationPath设置为/api，我们需要通过在 中设置属性来配置SpringDoc在何处查找定义application.properties：

springdoc.api-docs.path=/api/openapi.json

您还可以使用以下命令更改Swagger的 URL ：

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

其他事宜：

当应用程序作为.jar文件运行时，可能会出现另一个问题：

尝试从 jar 文件运行时，Spring Boot 应用程序将无法运行

在这种情况下，我通过使用反射库扫描所有组件找到了解决方案，如下org.reflections所示：

    private void scan(String... packages) {
        for (String packageName : packages) {
            Reflections reflections = new Reflections(packageName);
            reflections.getTypesAnnotatedWith(Provider.class).parallelStream().forEach(clazz -> register(clazz));
            reflections.getTypesAnnotatedWith(Path.class).parallelStream().forEach(clazz -> register(clazz));
        }
    }