基于Jakarta.ws.rs的Spring Boot项目如何生成OpenAPI文档？

• 通过IntelliJ IDEA向导创建Spring Boot项目（spring-boot-starter-parent版本3.4.0），引入spring-boot-starter-jersey依赖。
• 创建HelloWorldResource类：

@Path("/hello-world")
public class HelloWorldResource {
    @GET
    @Produces("text/plain")
    public String hello() {
        return "Hello, World!";
    }
}

• 创建JerseyConfig类：

@Component
public class JerseyConfig extends ResourceConfig {
    public JerseyConfig() {
        register(HelloWorldResource.class);
    }
}

• 当前资源可通过http://localhost:8080/hello-world访问。

问题 #

如何为使用jakarta.ws.rs注解（原JAX-RS）的该项目添加OpenAPI描述生成功能？

备注 #

有人建议使用springdoc-openapi-starter-webmvc-ui，但根据官方文档，该组件不支持Jersey：

springdoc-openapi支持Jersey吗？

• 如果你使用JAX-RS并以Jersey作为实现（比如使用@Path注解），我们不支持这种场景。
• 我们只支持通过Spring托管Bean（比如@RestController）暴露的Rest端点。

由于springdoc-openapi的webmvc组件不支持Jersey，推荐使用Swagger Core（OpenAPI 3.x）的JAX-RS集成方案，具体步骤如下：

1. 添加依赖 #

Maven（pom.xml） #

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2</artifactId>
    <version>2.2.20</version>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2-servlet-initializer-v2</artifactId>
    <version>2.2.20</version>
</dependency>
<!-- 可选：添加Swagger UI依赖以可视化文档 -->
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>5.17.14</version>
</dependency>

Gradle（build.gradle） #

implementation 'io.swagger.core.v3:swagger-jaxrs2:2.2.20'
implementation 'io.swagger.core.v3:swagger-jaxrs2-servlet-initializer-v2:2.2.20'
// 可选：添加Swagger UI依赖以可视化文档
implementation 'org.webjars:swagger-ui:5.17.14'

2. 配置OpenAPI元数据 #

创建配置类定义API的基础信息：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Jersey Demo API")
                        .version("1.0")
                        .description("基于Spring Boot + Jersey的OpenAPI示例"));
    }
}

3. 修改Jersey配置，注册Swagger组件 #

更新JerseyConfig类，添加Swagger相关组件的注册：

import io.swagger.v3.jaxrs2.integration.resources.OpenApiResource;
import org.springframework.stereotype.Component;
import org.glassfish.jersey.server.ResourceConfig;

@Component
public class JerseyConfig extends ResourceConfig {
    public JerseyConfig() {
        // 注册自定义资源
        register(HelloWorldResource.class);
        // 注册Swagger OpenAPI资源，用于生成openapi.json
        register(OpenApiResource.class);
    }
}

4. 访问OpenAPI文档 #

启动项目后：

• OpenAPI JSON描述：http://localhost:8080/openapi.json
• 若添加了Swagger UI，访问地址：http://localhost:8080/webjars/swagger-ui/index.html?url=/openapi.json

可选：丰富API文档注解 #

给资源类添加OpenAPI注解，提升文档详细程度：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/hello-world")
public class HelloWorldResource {
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Operation(summary = "打招呼接口", description = "返回简单的问候文本")
    @ApiResponse(responseCode = "200", description = "成功返回问候语")
    public String hello() {
        return "Hello, World!";
    }
}

内容的提问来源于stack exchange，提问作者nik0x1