如何为Spring Boot + Jersey项目自动生成OPENAPI文档？

针对Spring Boot与Jersey结合的项目，有两种可靠的自动生成OpenAPI文档的方案：

方案一：Swagger Core + Spring Boot整合 #

Swagger Core原生支持Jersey，同时可以和Spring Boot无缝配合，步骤如下：

1. 添加Maven依赖

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2</artifactId>
    <version>2.2.15</version>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-core</artifactId>
    <version>2.2.15</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

2. 注册Jersey的Swagger资源类
   在你的Jersey配置类（继承ResourceConfig的类）中注册Swagger相关资源：

@Configuration
public class JerseyConfig extends ResourceConfig {
    public JerseyConfig() {
        // 注册你的Jersey资源类
        register(YourJerseyResource.class);
        // 注册Swagger核心资源
        register(OpenApiResource.class);
        register(SwaggerUiResource.class);
        // 配置OpenAPI元数据
        OpenAPI openAPI = new OpenAPI()
                .info(new Info().title("你的API文档")
                        .version("1.0.0")
                        .description("Spring Boot + Jersey项目API"));
        OpenApiConfiguration openApiConfiguration = new OpenApiConfiguration()
                .openAPI(openAPI);
        register(openApiConfiguration);
    }
}

3. 启动项目后，访问/swagger-ui.html即可查看自动生成的文档，同时/v3/api-docs会输出JSON格式的OpenAPI规范。

方案二：OpenAPI Generator Maven插件 #

如果需要直接生成静态的OpenAPI文档文件，可以用这个插件，它能扫描Jersey的JAX-RS注解和Spring的相关注解：

1. 在pom.xml中添加插件配置

<build>
    <plugins>
        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>6.6.0</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <inputSpec>${project.basedir}/src/main/resources/openapi-template.yaml</inputSpec>
                        <generatorName>html</generatorName>
                        <output>${project.build.directory}/openapi-docs</output>
                        <!-- 扫描你的Jersey资源类包路径 -->
                        <configOptions>
                            <sourceFolder>src/main/java</sourceFolder>
                            <apiPackage>com.yourpackage.jersey.resources</apiPackage>
                        </configOptions>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2. 执行mvn clean generate，插件会扫描指定包下的Jersey资源类（带有@Path、@GET等JAX-RS注解的类），结合你提供的基础模板生成HTML格式的OpenAPI文档。

注意：两种方案都需要你在Jersey资源类上添加必要的Swagger/OpenAPI注解，比如@Operation、@Parameter、@ApiResponse等，这样生成的文档才会包含完整的接口描述信息。

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