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: [e-mail]
    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自动生成的文档了。

<img src="http://img.bigcherry.vip/image-20230228134358787.png" alt="image-20230228134358787" style="zoom:50%;" />

附录

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