如何基于现有Jax-RS应用通过Maven生成OpenAPI规范文件？

推荐插件：SmallRye OpenAPI Maven Plugin #

SmallRye OpenAPI是Eclipse MicroProfile规范的实现，可直接解析javax.ws.rs.*注解生成OpenAPI 3.x规范文件，完全不需要添加Swagger/OpenAPI专属注解，匹配你的需求。

配置步骤 #

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

<build>
    <plugins>
        <plugin>
            <groupId>io.smallrye</groupId>
            <artifactId>smallrye-open-api-maven-plugin</artifactId>
            <version>2.2.1</version> <!-- 建议使用最新稳定版 -->
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <phase>compile</phase> <!-- 绑定到编译阶段自动执行 -->
                </execution>
            </executions>
            <configuration>
                <outputFileName>openapi.json</outputFileName>
                <outputDirectory>${project.build.directory}/generated-resources</outputDirectory>
                <scanDependencies>false</scanDependencies> <!-- 可选：是否扫描依赖中的类 -->
                <packages>
                    <package>com.yourcompany.yourproject.rest</package> <!-- 指定你的JAX-RS资源包路径 -->
                </packages>
            </configuration>
        </plugin>
    </plugins>
</build>

2. 执行生成命令
   可以直接绑定compile阶段，执行mvn compile自动生成文件；也可单独执行插件目标：

mvn smallrye-open-api:generate

生成的文件会输出到target/generated-resources/openapi.json，若需YAML格式，将outputFileName改为openapi.yaml即可。

其他可选插件：Swagger Core Maven Plugin #

注意这不是你提到的反向生成类的swagger-maven-plugin，而是swagger-core系列的maven插件，同样支持从JAX-RS注解生成Swagger/OpenAPI规范，无需额外注解：

配置示例 #

<build>
    <plugins>
        <plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-jaxrs-maven-plugin</artifactId>
            <version>2.2.15</version>
            <executions>
                <execution>
                    <goals>
                        <goal>resolve</goal>
                    </goals>
                    <phase>compile</phase>
                </execution>
            </executions>
            <configuration>
                <outputFileName>openapi.json</outputFileName>
                <outputPath>${project.build.directory}/generated-resources</outputPath>
                <resourcePackages>
                    <package>com.yourcompany.yourproject.rest</package>
                </resourcePackages>
                <openAPI3>true</openAPI3> <!-- 生成OpenAPI 3.x规范 -->
            </configuration>
        </plugin>
    </plugins>
</build>

执行命令：

mvn swagger-jaxrs:resolve

关键说明 #

• 两个插件均支持解析标准javax.ws.rs.*注解，包括@Path、@GET、@POST、@Produces、@Consumes、@PathParam、@QueryParam等，还能自动识别实体类字段作为请求/响应模型。
• 无需修改现有代码添加任何Swagger/OpenAPI专属注解（如@Api、@ApiOperation），完全基于现有JAX-RS契约生成规范。
• 可通过插件配置自定义规范元数据（如标题、版本、描述），例如在SmallRye插件中添加：

<configuration>
    <!-- 其他配置 -->
    <info>
        <title>你的API标题</title>
        <version>1.0.0</version>
        <description>基于JAX-RS注解生成的API文档</description>
    </info>
</configuration>

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