java接口文档工具 swagger2和swagger3对比

maven依赖：

swagger2+swagger3 都支持：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>${swagger.version}</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>

maven依赖：

只支持swagger3：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
</dependency>

Swagger2 注解 VS OpenAPI3 注解 完整对照表

springfox-boot-starter 3.x，两套都生效，新版优先

一、控制器 & 接口分组

用途	Swagger2（旧）	OpenAPI3（新 推荐）
控制器类分组 / 描述	@Api(tags = "模块名")	@Tag(name = "模块名", description = "描述")

二、接口方法说明

用途	Swagger2（旧）	OpenAPI3（新 推荐）
接口功能简介	@ApiOperation(value = "接口名称", notes = "详细描述")	@Operation(summary = "接口名称", description = "详细描述")

三、请求参数注解

用途	Swagger2（旧）	OpenAPI3（新 推荐）
普通入参说明	@ApiParam(value = "参数说明")	@Parameter(description = "参数说明")
全局忽略参数	@ApiIgnore	@Hidden

四、实体类 / VO/DTO 文档

用途	Swagger2（旧）	OpenAPI3（新 推荐）
实体类整体描述	@ApiModel(description = "用户实体")	@Schema(description = "用户实体")
实体字段说明	@ApiModelProperty(value = "用户名", example = "张三")	@Schema(description = "用户名", example = "张三")

五、全局响应 & 错误码

用途	Swagger2（旧）	OpenAPI3（新 推荐）
统一响应状态码	@ApiResponses + @ApiResponse	@ApiResponses + @ApiResponse（通用保留）

六、权限 / Header 配置

用途	Swagger2（旧）	OpenAPI3（新 推荐）
请求头 Token	@ApiImplicitParam	@RequestHeader + @Parameter

---

二、关键补充（你项目重点）

1. 依赖：springfox-boot-starter 3.x
   • 双注解完全兼容、同时生效
   • 冲突时：@Tag / @Operation 优先级 > @Api / @ApiOperation
2. 包路径区分（防止导错包）
   • 旧版 Swagger2：io.swagger.annotations.xxx
   • 新版 OpenAPI3：io.swagger.v3.oas.annotations.xxx
3. 强制规范： 新项目全部使用右侧 OpenAPI3 注解，统一风格、方便后续升级。

旧版 Swagger2:

@Api(tags = "角色管理")
@RestController
@RequestMapping("/role")
public class RoleController {

    @ApiOperation("角色列表查询")
    @GetMapping("/list")
    public Result list(){ }
}

新版 OpenAPI3:

@Tag(name = "角色管理", description = "角色权限相关接口")
@RestController
@RequestMapping("/role")
public class RoleController {

    @Operation(summary = "角色列表查询", description = "分页获取全部角色")
    @GetMapping("/list")
    public Result list(){ }
}