庖丁解牛：剖析Swagger与SpringDoc的异同，发现API文档新大陆

2023-12-01 02:42:50

前言

上周松哥写了一篇文章和小伙伴们分享 Swagger3 在 Spring Boot 中的用法，评论中有不少小伙伴推荐 Spring Doc，松哥趁着休息时间抽空看了下，这个东西确实不错，不看不知道，一看吓一跳，原来 API 文档还可以这么玩。

作为一名合格的技术博主，肯定是要紧跟时代的步伐，去尝试新鲜事物，既然小伙伴们如此推荐 Spring Doc，松哥自然也要亲自体验一番，写一篇 Spring Doc 的文章分享给大家，希望对大家有所帮助。

Swagger 和 SpringDoc 的异同

在开始介绍 SpringDoc 之前，我们先来简单了解一下 Swagger。Swagger 是一款强大的 API 文档生成工具，它可以根据注解自动生成 RESTful API 的文档，包括 API 的路径、参数、返回值等等，Swagger 的优势在于它的易用性和广泛的社区支持，成为目前最流行的 API 文档工具之一。

SpringDoc 是一个基于 Swagger 构建的 API 文档生成器，它继承了 Swagger 的优点，同时又针对 Spring Boot 做了进一步的优化，在使用 SpringDoc 时，我们可以通过配置的方式来定制 API 文档的风格和内容，从而更加契合我们的项目需求。

Swagger 和 SpringDoc 的主要区别在于：

SpringDoc 依赖于 Springfox，而 Swagger 依赖于 Swagger-Core。
SpringDoc 支持 OpenAPI 3.0 规范，而 Swagger 只支持 OpenAPI 2.0 规范。
SpringDoc 提供了一个更简洁的配置方式，而 Swagger 的配置方式相对复杂。
SpringDoc 提供了一个更友好的 UI 界面，而 Swagger 的 UI 界面相对简单。

如何使用 SpringDoc

接下来，我们就来介绍一下如何使用 SpringDoc 来生成 API 文档。

首先，我们需要在项目中添加 SpringDoc 的依赖，在 pom.xml 文件中添加如下代码：

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.6.11</version>
</dependency>

然后，我们需要在 Spring Boot 项目中配置 SpringDoc，在 application.properties 文件中添加如下代码：

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

最后，我们只需要在我们的 Controller 中使用 @ApiOperation、@ApiParam 等注解来标记 API 的相关信息，SpringDoc 就会根据这些注解自动生成 API 文档。

例如，我们有一个这样的 Controller：

@RestController
@RequestMapping("/user")
public class UserController {

  @PostMapping
  public User createUser(@RequestBody User user) {
    return userService.createUser(user);
  }
}

我们可以使用 @ApiOperation 和 @ApiParam 注解来标记 API 的相关信息：

@RestController
@RequestMapping("/user")
public class UserController {

  @PostMapping
  @ApiOperation(value = "Create a new user")
  public User createUser(@ApiParam(value = "The user to be created") @RequestBody User user) {
    return userService.createUser(user);
  }
}