前后端对接，就得有一个好的的接口文档，具体到：接口的名称，说明，入参字段，出参字段，是否必传，参数类型等等，这里记录一下使用的swagger ui组件 knife4j-spring-ui。

knife4j-spring-ui 是swagger的一个增强版，相比官方ui，其界面更美观，功能更强大，字段说明更清晰直观，测试起来更方便对比一下：

官方UI：

全新UI：

集成在sprintboot项目中

一、pom文件添加依赖

		<!-- 封装了swagger2 -->
		<dependency>
			<groupId>io.github.wilson-he</groupId>
			<artifactId>swagger2-spring-boot-starter</artifactId>
			<version>1.1.2</version>
		</dependency>
		<!-- swagger增强版ui，相比官方ui，界面更美观，功能更强大 -->
        <!-- 如果springBoot版本过高，可能会出现错误 -->
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>knife4j-spring-ui</artifactId>
			<version>3.0.2</version>
		</dependency>

二、配置文件添加配置（可以不配）

配置基本的文档说明信息，如果不配置，就是默认的

#####  swagger文档部分配置 ####
swagger:
  # 生产环境改为false（改为false后swagger-ui.html则无法访问）
  enabled: true
  docket:
    api-info:
      title: xxx管理平台接口api
      description: 文件详细说明
      version: 1.0.0
      # 维护者信息
      contact:
        name: zhaoheng
        url: https://blog.csdn.net/Muscleheng?type=blog

三、配置swagger静态页面访问路径

如果不配置，访问swagger页面时可能出现404

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    /**
     * 配置静态资源访问路径
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 静态资源访问路径和存放路径配置
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/","classpath:/public/");
        // swagger访问配置
        registry.addResourceHandler("/**").addResourceLocations("classpath:/META-INF/resources/","classpath:/META-INF/resources/webjars/");
    }
}

四、编写代码测试成果

在对应的出入参实体类、字段上添加swagger的注解，就能在接口文档上显示对应的字段说明

1. model实体示例

出参实体：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
 
@Data
@ApiModel("用户信息出参实体")
public class UserVO {
 
    @ApiModelProperty(value = "编号")
    private Long id;
 
    @ApiModelProperty(value = "姓名")
    private String name;
 
    @ApiModelProperty(value = "年龄")
    private Integer age;
}

入参实体：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
 
@Data
@ApiModel("用户信息查询入参实体")
public class QueryUserRO {
 
    @ApiModelProperty(value = "编号",required = true)
    private Long id;
 
    @ApiModelProperty(value = "姓名",required = false)
    private String name;
}

2. controller示例

@Api(tags = "用户管理-api")
@RestController
@RequestMapping("/demo1")
public class Demo1Controller {
 
    @ApiOperation("查询用户接口1")
    @PostMapping("/getUser")
    public UserVO getUser(@RequestBody QueryUserRO queryUserRO){
        return new UserVO();
    }
 
    @ApiOperation("查询用户接口2")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", dataType = "Long", required = true),
            @ApiImplicitParam(name = "name", value = "用户姓名", dataType = "String", required = false)
    })
    @PostMapping("/getUser2")
    public UserVO getUser2(@RequestParam(name = "id",required = true) Long id, @RequestParam(name = "name",required = false) String name){
        return new UserVO();
    }
}

启动项目，可通过两个地址访问到swagger文档：

官方文档UI界面：127.0.0.1:8080/swagger-ui.html

增强版UI界面：127.0.0.1:8080/doc.html

swagger2的全新UI组件