doc怎么打开（你会用哪个）

小伙伴们都知道，现在 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 都给大家介绍完了，你更喜欢哪个呢？可以在评论区告诉我哦。关注互联网架构小马哥，干货天天都不断！