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

原创已于 2026-04-27 01:44:22 修改 · 52 阅读

0 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

于 2026-04-27 01:43:04 首次发布

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`

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

依赖：springfox-boot-starter 3.x
- 双注解完全兼容、同时生效
- 冲突时：@Tag / @Operation 优先级 > @Api / @ApiOperation
包路径区分（防止导错包）
- 旧版 Swagger2：io.swagger.annotations.xxx
- 新版 OpenAPI3：io.swagger.v3.oas.annotations.xxx
强制规范：

新项目全部使用右侧 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(){ }
}

标签