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(){ }
}
相关推荐
Java展博21 分钟前
[Go 后端转场] 从 try-catch 到 if err != nil:写惯 Java 的人第一次上手最别扭的 4 件事
java·开发语言·golang
starzy199028 分钟前
Hadoop介绍总结:一张图理清组件、生态与版本
java·hadoop
SEO_juper28 分钟前
Node.js 全站 SEO 体检报告生成器:一次查完标题、描述、canonical、H1、图片
开发语言·前端·node.js·html·bash
Summer-Bright1 小时前
企业落地智能体,供应链签名还是空白:1862 个 MCP 服务器无认证裸奔
服务器·人工智能·github·mcp
yyuuuzz1 小时前
nginx 502 排查,先看上游超时那一行
android·java·运维·nginx·502
Java后端的Ai之路1 小时前
Java并发编程25-集合的线程安全
java·安全·面试
NoteDeep 深度笔记1 小时前
DOM 被改乱了怎么办?Notedeep 编辑器的 normalize 设计
前端·javascript·编辑器
zhanlang02171 小时前
HTML 零基础入门到企业实战【第七章 7.2】form 标签属性:action、method、name、target 详解
前端·html
CoderYanger1 小时前
Java EE 进阶:9.MyBatis 操作数据库(进阶)(第一弹)
java·数据库·spring·面试·java-ee·tomcat·mybatis
码云社区2 小时前
Java租房平台源码方案:Vue 3房源审核、UniApp预约看房与房东管理
java·vue.js