前后端对接，就得有一个好的的接口文档，具体到：接口的名称，说明，入参字段，出参字段，是否必传，参数类型等等，这里记录一下使用的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，界面更美观，功能更强大 -->
<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
?
