小伙伴们都知道，现在 Java 开发基本上都是前后端分离模式了。既然要搞前后端分离，就离不开在线接口文档，而要想实现在线接口文档，我们又有很多不同的选择，其中 Swagger 和 SpringDoc 是开源领域的两个重要产品。今天百泽老师，就来手把手地教大家如何使用这两个工具！并且来看看这两个工具哪个更好？
接下来百泽给大家分别介绍一下这两个产品。
一. Swagger
Swagger在2020年其实就更新到 3.0 版本了，现在大家如果在最新版的 Spring Boot 中使用老版本的 Swagger，多多少少都会遇到一些兼容性的问题。既然Swagger3 迟早都要学，那不如就今天开始学吧！
今天我们就来看看，在 Spring Boot2.7.2 中如何使用 Swagger3。
1. 添加依赖
首先我们创建一个 Spring Boot 项目，并引入 Swagger3 的核心依赖包，如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>以前在旧版的 Swagger 中，我们需要添加的依赖包有两个，现在只需要添加一个依赖即可。
2. 核心配置
接下来我们在启动类上添加两个注解，开启Swagger功能。
@SpringBootApplication
//开启swagger
@EnableSwagger2
@EnableOpenApi
@EnableWebMvc
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}现在准备工作就 OK 啦，Swagger 文档已经可以自动生成了，并且也可以在线访问了。
接下来让我们可以启动项目，然后在浏览器中输入如下地址：
http://localhost:8080/swagger-ui/index.html
现在我们就可以查看自动生成的 Swagger 文档了。
如果大家用过以前旧版的 Swagger，应该可以看出来，这个访问地址跟以前旧版的 Swagger 访问地址不太一样。
大家看到，默认的接口中有一个是 BasicErrorController，这个接口是 Spring Boot 默认提供的异常处理器。由于我们现在没有设置 Swagger 要扫描哪些包，所以默认所有暴露的接口都被扫描了，所以就连同这个默认的异常处理接口一起被扫描出来了。
如果我们需要对这个接口做一些定制，也是可以的，如下所示：
@Configuration
public class Swagger2Config {
@Bean
Docket docket() {
return new Docket(DocumentationType.OAS_30)
//配置网站的基本信息
.apiInfo(new ApiInfoBuilder()
//网站标题
.title("锋迷商城项目在线接口文档")
//标题后面的版本号
.version("v1.0")
.description("锋迷商城项目接口文档")
//联系人信息
.contact(new Contact("qf", "http://www.qfedu.com", "111@qq.com"))
.build())
.select()
//指定接口的位置
.apis(RequestHandlerSelectors.basePackage("com.qfedu.swagger_demo.controller"))
.build();
}
}配置完成之后，Swagger的网页就会更新了。
3. 接口配置
默认的接口信息是根据代码生成的，很多都是英文，这并不符合我们的日常使用习惯，所以我们还是想把接口信息定制成中文的，我们来看下：
@RestController
@Api(tags = "用户管理相关接口")
@RequestMapping("/user")
public class UserController {
@PostMapping("/")
@ApiOperation("添加用户的接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),
@ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "深圳", required = true)
})
public RespBean addUser(String username, @RequestParam(required = true) String address) {
return new RespBean();
}
@GetMapping("/")
@ApiOperation("根据id查询用户的接口")
@ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99", required = true)
public User getUserById(@PathVariable Integer id) {
User user = new User();
user.setId(id);
return user;
}
@PutMapping("/{id}")
@ApiOperation("根据id更新用户的接口")
public User updateUserById(@RequestBody User user) {
return user;
}
}这些都是 Swagger 的常用注解，我们来逐个看看都有什么功能：
@Api 注解可以用来描述一个 Controller 整体功能；
@ApiOperation 注解用来描述一个方法的具体功能；
@ApiImplicitParam 注解用来描述一个方法的参数含义，我们可以通过这个注解来配置参数的中文含义，或者给参数设置默认值，这样就可以在接口测试的时候可以避免手动输入值，提高测试效率；
如果某一个接口方法有多个参数，那么就需要使用多个 @ApiImplicitParam 注解来描述接口参数，多个 @ApiImplicitParam 注解放在一个 @ApiImplicitParams 注解中集中管理即可；
@ApiImplicitParam 注解中虽然可以指定参数是必填的，但是却不能代替 @RequestParam(required = true) ，前者的必填只是在 Swagger 框架内必填，抛弃了 Swagger ，这个限制就没用了，所以假如开发者需要指定一个参数必填， @RequestParam(required = true) 注解还是不能省略；
如果参数是一个对象(例如上文的更新接口)，对于参数的描述也可以放在实体类中。例如下面一段代码：
@ApiModel
public class User {
@ApiModelProperty(value = "用户id")
private Integer id;
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "用户地址")
private String address;
//getter/setter
}配置完成后，再去刷新页面，就可以看到刚刚配置的文档信息啦。
二. 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，那么只需要添加如下依赖即可：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webmvc-core</artifactId>
<version>1.6.9</version>
</dependency>此时就会针对项目中的接口，自动生成接口对应的 JSON 文档。这个单纯的 JSON 格式看着肯定不是很方便，我们还是得有个页面，接下来添加如下依赖，即可通过网页来展示上面的 JSON 数据了：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.9</version>
</dependency>这个网页说白了其实就是 Swagger UI。
2. 从 Swagger 到 SpringDoc
如果有小伙伴已经在项目中使用 Swagger了，其实也可以非常方便地切换到 SpringDoc 上面来，切换的时候，首先引入 SpringDoc 依赖：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.9</version>
</dependency>Swagger 和 SpringDoc 注解的对应关系如下：
@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden=false) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(acc essMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Op eration(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @A piResponse(responseCode = "404", description = "foo")
按照这样的方式，我们更换注解就可以轻松地切换到SpringDoc上去啦。
三. 小结
好啦，现在百泽就把Swagger 和 SpringDoc 都给大家介绍完了，你更喜欢哪个呢？可以在评论区告诉百泽哦。关注Java架构栈，干货天天都不断！
本月福利，关注公众号回复【福利】抢书咯！
今日份干货，学会的同学回复“666”！
精选第一名，可以领取办公鼠标垫一个！
点击【阅读原文】，零基础免费学Java！
原文作者：Java架构栈；如有侵权，请联系管理员删除。
