Spring Boot | 整合Swagger、Knife4j自动生成API文档

前言

在平时的工作中，通常需要给Web工程师或者第三方开发工程师提供接口文档。这就要求我们在更新代码的同时同步维护相关的接口文档。使用Swagger可以自动生成API文档，大减轻开发者维护接口文档的工作量。

Swagger简介

Swagger（官网地址：https://swagger.io/）是一个接口文档自动生成工具，可以根据源码中的注解自动生成接口文档。

Knife4j简介

Knife4j（官网地址：https://doc.xiaominfo.com/）是一个工具类库，用于美化、强化Swagger。

Swagger常用注解

@Api

@Api注解用于标注控制器类。

@RestController
@Api(tags = "用户接口")
@RequestMapping("/user")
public class UserController {
  // ...
}           

@ApiOperation

@ApiOperation用于标注控制器类中的方法。

@ApiOperation(value = "所有用户列表")
@GetMapping("/all")
public List<User> all() {
  // ...
}           

@ApiParam

@ApiParam用于标注控制器类中方法的参数。

@ApiModel

@ApiModel用于标注数据对象，比如VO。

@Data
@AllArgsConstructor
@ApiModel("用户")
public class User {
  // ...
}           

@ApiModelPropert

@ApiModelPropert用于标注数据对象的属性。

@ApiModelProperty("用户编码")
private String usercode;           

集成步骤

1、引入Maven依赖

在pom.xml文件中添加如下依赖：

<!-- 引入Knife4j的官方start包，Spring Boot版本<3.0 -->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
  <version>4.0.0</version>
</dependency>           

2、配置信息

修改配置的application.yml配置文件，添加如下配置：

#swagger公共信息
swagger:
  title: DDCherry接口文档系统
  description: DDCherry接口文档系统
  license: Powered By ddcherry
  license-url: http://www.bigcherry.vip/
  terms-of-service-url: http://www.bigcherry.vip/
  version: 1.0.0
  contact:
    name: 嗨皮汪小成
    email: [email protected]
    url: https://juejin.cn/user/3614849960783160           

3、配置信息类

package cn.ddcherry.springboot.demo.config;

import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Data
@Component
@ConfigurationProperties("swagger")
public class SwaggerProperties {
  private String title;
  private String description;
  private String termsOfServiceUrl;
  private String license;
  private String licenseUrl;
  private String version;
  private Contract contract = new Contract();

  @Data
  @NoArgsConstructor
  public static class Contract {
    private String name;
    private String url;
    private String email;
  }
}           

通过@ConfigurationProperties注解，我们可以将配置文件中的所有前缀为swagger的属性值绑定到SwaggerProperties类中。

4、配置类

package cn.ddcherry.springboot.demo.config;

import lombok.AllArgsConstructor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@AllArgsConstructor
@EnableSwagger2WebMvc
public class SwaggerConfig {

  private SwaggerProperties swaggerProperties;

  @Bean(value = "dockerBean")
  public Docket dockerBean() {
    //指定使用Swagger2规范
    return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      // 分组名称
      .groupName(swaggerProperties.getVersion())
      .select()
      // 这里指定Controller扫描包路径
      .apis(RequestHandlerSelectors.basePackage("cn.ddcherry.springboot.demo.controller"))
      .paths(PathSelectors.any())
      .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
      .title(swaggerProperties.getTitle())
      .description(swaggerProperties.getDescription())
      .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
      .contact(new Contact(swaggerProperties.getContract().getName(),
        swaggerProperties.getContract().getUrl(),
        swaggerProperties.getContract().getEmail()))
      .version(swaggerProperties.getVersion())
      .build();
  }
}           

@EnableSwagger2WebMvc注解用于启用Swagger API文档生成器。@EnableSwagger2WebMvc注解可以在Java配置类或者Spring Boot的启动类上使用。

我们在SwaggerConfig.java配置类中配置了DocketBean，用于设置Swagger相关信息。

5、实体类

编写一个用于演示的实体类 —— User.java。

package cn.ddcherry.springboot.demo.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;

@Data
@AllArgsConstructor
@ApiModel("用户")
public class User {
  @ApiModelProperty("主键")
  private String id;
  @ApiModelProperty("用户编码")
  private String usercode;
  @ApiModelProperty("用户姓名")
  private String name;
}           

6、控制器类

package cn.ddcherry.springboot.demo.controller;

import cn.ddcherry.springboot.demo.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Arrays;
import java.util.List;

@RestController
@Api(tags = "用户接口")
@RequestMapping("/user")
public class UserController {

  @ApiOperation(value = "所有用户列表")
  @GetMapping("/all")
  public List<User> all() {
    return Arrays.asList(new User("001", "wxc", "嗨皮汪小成"), new User("002", "dd", "丁丁"));
  }
}           

7、启动项目

启动项目，在浏览器地址栏输入http://localhost:8080/doc.html就可以看到Swagger自动生成的文档了。

附录

项目源码地址：https://github.com/wanggch/spring-boot-demos/tree/main/04.spring-boot-swagger