如何实现后端开发框架（九）-自动生成API文档

1.问题描述

在前后端分离的软件系统开发中，一般后端完成RESTful API接口后，需要将API使用方法告诉前端来进行集成和联调测试。如果后端采用写API文档的方式，一是很麻烦耗时，而是代码改动后文档也要及时更新才行。有没有更方便的方式来生成API文档呢？

2.实现思路

我们利用Springdoc工具包来根据后端代码自动生成对应的API文档。

Springdoc也叫Swagger3，网上有很多资料说的其实是Swagger2的使用方式。

Swagger2使用的工具包是springfox，Swagger2可以在Springboot 2.3及以下版本中使用。springfox已经很长时间不更新了，不推荐使用。

Swagger3使用的工具包是springdoc-openapi-ui，Swagger3可以在Springboot 2.4及以上版本中使用。

我这里使用的是Springboot 2.6，所以我要使用的是springdoc-openapi-ui工具包。

3.实现步骤

3.1.引入依赖包

这里添加Springboot 2.6对应的Springdoc依赖包版本。

所有Springboot版本号对应的Springdoc版本号见官方文档：https://springdoc.org/#what-is-the-compatibility-matrix-of-springdoc-openapi-with-spring-boot

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

3.2.配置首页信息

Opendoc完整的配置参数清单见官方文档：https://springdoc.org/#properties

/**
 * 默认前端页面地址为：http://ip:port/swagger-ui.html <br>
 * 默认后端api的json地址为：http://ip:port/v3/api-docs
 */
@Configuration
@OpenAPIDefinition(info = @Info(title = "API", version = "1.0", description = "API v1.0"))
public class OpenApiConfig {}

3.3.使用API文档注解

在实体类中使用：

@TableName：标识数据库表的相关信息

@Schema：标识表字段的相关信息

完整注解使用方法见官方demo：https://springdoc.org/#demos

@Data
@EqualsAndHashCode(callSuper = true)
@TableName("SECURITY_USER")
public class User extends MyBaseEntity {
  private static final long serialVersionUID = 1L;

  @Schema(description = "登录名")
  @TableField(value = "ACCOUNT")
  private String account;

  @Schema(description = "姓名")
  @TableField("REAL_NAME")
  private String realName;

  @Schema(description = "排序编号")
  @TableField("SORT")
  private Integer sort;
}

在API方法中使用：

@Tag：标识类的相关信息

@Operation：标识API方法的相关信息

完整注解使用方法见官方demo：https://springdoc.org/#demos

@RestController
@RequestMapping("/test/user")
@Tag(name = "UserController", description = "用户信息接口")
public class UserController extends MyBaseController<UserService, User> {
  /**
   * 根据条件查询所有记录
   *
   * @param user
   * @return
   */
  @Operation(description = "根据条件查询所有记录")
  @RequestMapping(value = "/list", method = RequestMethod.POST)
  public List<User> list(@RequestBody(required = false) User user) {
    List<SqlParam> sqlParams = new ArrayList<>();
    SqlParam sqlParam1 = new SqlParam("ACCOUNT", user.getAccount(), SqlOperator.EQ);
    SqlParam sqlParam2 = new SqlParam("REAL_NAME", user.getRealName(), SqlOperator.LIKE);
    sqlParams.add(sqlParam1);
    sqlParams.add(sqlParam2);

    SqlParam sortParam = new SqlParam("SORT", SqlOperator.ORDER_BY_ASC);
    sqlParams.add(sortParam);

    List<User> result = myBaseService.customQuery(sqlParams);
    return result;
  }

  /**
   * 根据条件分页查询记录
   *
   * @param user
   * @return
   */
  @Operation(description = "根据条件分页查询记录")
  @RequestMapping(value = "/pageList", method = RequestMethod.POST)
  public MyPage<User> pageList(@RequestBody User user) {
    List<SqlParam> sqlParams = new ArrayList<>();
    SqlParam sqlParam1 = new SqlParam("ACCOUNT", user.getAccount(), SqlOperator.EQ);
    // SqlParam2第三个参数表示“ACCOUNT”和”REAL_NAME“这两个查询条件是”OR”关系，默认是“AND”关系
    SqlParam sqlParam2 =
        new SqlParam("REAL_NAME", user.getRealName(), SqlOperator.LIKE, SqlOperator.OR);
    sqlParams.add(sqlParam1);
    sqlParams.add(sqlParam2);

    SqlParam sortParam = new SqlParam("SORT", SqlOperator.ORDER_BY_ASC);
    sqlParams.add(sortParam);

    MyPage<User> result =
        myBaseService.customPagingQuery(sqlParams, user.getCurrentPage(), user.getPageSize());
    return result;
  }
}

4.测试验证

启动后端Springboot系统后：

默认API前端页面访问地址为：http://ip:port/swagger-ui.html

默认后端api的json文件访问地址为：http://ip:port/v3/api-docs

页面功能显示如下：

5.完整代码

完整代码见以下Git仓库中的”api-doc”子项目：

https://github.com/randy0098/framework-samples