有没有支持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生成OpenAPI 3.0规范的Spring Boot配置

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

1. 在pom.xml
2. Extend
3. 中包括spring-boot-starter-jersey、swagger-core、swagger-annotations和swagger-jaxrs，并将包配置为扫描JAX-RS批注并注册Swagger的OpenAPIResource.class。如果要通过schema.
4. Optionally访问Swagger，请使用OpenAPIResource.class批注为端点和schema.
5. Optionally添加批注sprindoc-openapi-ui

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);
    }
}

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

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

OpenApiResource.class来自Swagger，提供/openapi.json端点。

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

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：

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

其他问题：

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

Spring boot application won't run when trying to run from the jar file

在这种情况下，我找到了一个解决方案，通过使用像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));
        }
    }

Answer 2

添加答案，因为我无法评论或编辑。

配置问题:当我尝试加载swagger-ui.html时，它被重定向到/swagger-ui/index.html?configUrl=/api/openapi.json/swagger-config，但是，没有用于swagger-

的内容。我是否遗漏了任何配置？

我也有同样的问题。我可以通过将以下属性添加到我的application.properties中来修复它

springdoc.swagger-ui.display-query-params=true

这个问题很奇怪，不知何故，解决方案甚至更奇怪。但是，嘿，它起作用了！

Answer 3

从1.6版本开始，SwaggerUiConfigProperties中删除了isDisplayQueryParams()，但此解决方案可以工作：

springdoc.swagger-ui.url=/api/openapi.json

原则：

1) GET /swagger-ui/index.html
2) GET /v3/api-docs/swagger-config
    [Response body]
    configUrl: "/v3/api-docs/swagger-config"
    oauth2RedirectUrl: "(...)"
    operationsSorter: "method"
    url: "/api/openapi.json" // <=> springdoc.swagger-ui.url
    validatorUrl: ""
3) GET /api/openapi.json