小伙伴们都知道，现在 Java 开发基本上都是前后端分离模式了。既然要搞前后端分离，就离不开在线接口文档，而要想实现在线接口文档，我们又有很多不同的选择，其中 Swagger 和 SpringDoc 是开源领域的两个重要产品。今天，就来手把手地教大家如何使用这两个工具!并且来看看这两个工具哪个更好?

　　接下来百泽给大家分别介绍一下这两个产品。

　　一. Swagger

　　Swagger在2020年其实就更新到 3.0 版本了，现在大家如果在最新版的 Spring Boot 中使用老版本的 Swagger，多多少少都会遇到一些兼容性的问题。既然Swagger3 迟早都要学，那不如就今天开始学吧!

　　今天我们就来看看，在 Spring Boot2.7.2 中如何使用 Swagger3。

　　1、添加依赖

　　首先我们创建一个 Spring Boot 项目，并引入 Swagger3 的核心依赖包，如下：

　　以前在旧版的 Swagger 中，我们需要添加的依赖包有两个，现在只需要添加一个依赖即可。

　　2、核心配置

　　接下来我们在启动类上添加两个注解，开启Swagger功能。

　　现在准备工作就 OK 啦，Swagger 文档已经可以自动生成了，并且也可以在线访问了。

　　接下来让我们可以启动项目，然后在浏览器中输入如下地址：

　　http://localhost:8080/swagger-ui/index.html

　　现在我们就可以查看自动生成的 Swagger 文档了。

　　如果大家用过以前旧版的 Swagger，应该可以看出来，这个访问地址跟以前旧版的 Swagger 访问地址不太一样。

　　大家看到，默认的接口中有一个是 BasicErrorController，这个接口是 Spring Boot 默认提供的异常处理器。由于我们现在没有设置 Swagger 要扫描哪些包，所以默认所有暴露的接口都被扫描了，所以就连同这个默认的异常处理接口一起被扫描出来了。

　　如果我们需要对这个接口做一些定制，也是可以的，如下所示：

　　配置完成之后，Swagger的网页就会更新了。

　　3、接口配置

　　默认的接口信息是根据代码生成的，很多都是英文，这并不符合我们的日常使用习惯，所以我们还是想把接口信息定制成中文的，我们来看下：

　　这些都是 Swagger 的常用注解，我们来逐个看看都有什么功能：

　　@Api 注解可以用来描述一个 Controller 整体功能;

　　@ApiOperation 注解用来描述一个方法的具体功能;

　　@ApiImplicitParam 注解用来描述一个方法的参数含义，我们可以通过这个注解来配置参数的中文含义，或者给参数设置默认值，这样就可以在接口测试的时候可以避免手动输入值，提高测试效率;

　　如果某一个接口方法有多个参数，那么就需要使用多个 @ApiImplicitParam 注解来描述接口参数，多个 @ApiImplicitParam 注解放在一个 @ApiImplicitParams 注解中集中管理即可;

　　@ApiImplicitParam 注解中虽然可以指定参数是必填的，但是却不能代替 @RequestParam(required = true) ，前者的必填只是在 Swagger 框架内必填，抛弃了 Swagger ，这个限制就没用了，所以假如开发者需要指定一个参数必填， @RequestParam(required = true) 注解还是不能省略;

　　如果参数是一个对象(例如上文的更新接口)，对于参数的描述也可以放在实体类中。例如下面一段代码：

　　配置完成后，再去刷新页面，就可以看到刚刚配置的文档信息啦。

　　二. SpringDoc

　　SpringDoc 是 OpenAPI 的另一个实现，我们前面第一小节使用的 Swagger 其实也是 OpenAPI 的一个实现。OpenApi 是业界的一个 API 文档标准，是一个规范。相比 Swagger，SpringDoc的功能更有规范和强大，SpringDoc 具有如下特性：

　　OpenAPI 3;

　　Spring Boot全系列都支持;

　　JSR-303中提供的一些注解，例如 @NotNull、@Min、@Max 以及 @Size 等;

　　Swagger-ui：SpringDoc 提供的接口 JSON ，也可以通过 Swagger-ui 展示出来。

　　OAuth 2

　　1、添加依赖

　　当我们使用 SpringDoc 的时候，如果只是想生成文档 JSON，那么只需要添加如下依赖即可：

　　此时就会针对项目中的接口，自动生成接口对应的 JSON 文档。这个单纯的 JSON 格式看着肯定不是很方便，我们还是得有个页面，接下来添加如下依赖，即可通过网页来展示上面的 JSON 数据了：

　　这个网页说白了其实就是 Swagger UI。

　　2、从 Swagger 到 SpringDoc

　　如果有小伙伴已经在项目中使用 Swagger了，其实也可以非常方便地切换到 SpringDoc 上面来，切换的时候，首先引入 SpringDoc 依赖：

　　Swagger 和 SpringDoc 注解的对应关系如下：

　　@Api → @Tag

　　@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = false) or @Hidden

　　@ApiImplicitParam → @Parameter

　　@ApiImplicitParams → @Parameters

　　@ApiModel → @Schema

　　@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)

　　@ApiModelProperty → @Schema

　　@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")

　　@ApiParam → @Parameter

　　@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

　　按照这样的方式，我们更换注解就可以轻松地切换到SpringDoc上去啦。

　　三. 小结

　　好啦，现在百泽就把Swagger 和 SpringDoc 都给大家介绍完了，你更喜欢哪个呢?

上一篇

Jmeter压力测试工具使用

下一篇

使用Feign组件出现Bug如何去定位？