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