knifie
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!
knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j
开始
1、springboot项目只需要引入如下依赖即可
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.5</version>
</dependency>
2、增加一个swagger配置类
package com.danseek.demo.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @Description: swagger配置类
* @Author: danseek
* @CreateTime: 2020-10-22 15:51
*/
@Configuration
@EnableSwagger2
@EnableKnife4j
@Profile({
"dev","test"})
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.useDefaultResponseMessages(false)
.groupName("后端接⼝⽂档")
.apiInfo(apiInfo())
.select()
//配置哪些路径和API会生成document
.apis(RequestHandlerSelectors.basePackage("com.danseek.demo.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文档")
.description("后台相关接口")
.contact(new Contact("danseek",null,null))
.version("1.0")
.build();
}
}
3、application.yml
server:
port: 8090
servlet:
context-path: /
spring:
application:
name: Knife4j-Demo
profiles:
active: dev
搭建完成，启动项目访问：http://192.168.1.210:8090/doc.html
swagger注解
接下来给控制器和请求参数加上注解让生成的文档更易读
package com.danseek.demo.controller;
import com.danseek.demo.entity.User;
import com.github.xiaoymin.knife4j.annotations.DynamicParameter;
import com.github.xiaoymin.knife4j.annotations.DynamicParameters;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
/**
* @Description: todo
* @Author: danseek
* @CreateTime: 2020-10-23 15:20
*/
@Api(value = "用户控制器",tags = "用户控制器")
@Slf4j
@RestController
@RequestMapping("/user")
public class UserController {
@GetMapping("obj")
// 设置接口标题、描述注解
@ApiOperation(value = "对象参数",notes = "获取用户")
// 如果请求参数是对象，只需要给user实体类的属性加上注解即可，这里不需要加
public User obj(User user){
User u = new User();
u.setUserName("danseek");
u.setMobile("13888888888");
return u;
}
@GetMapping("obj1")
@ApiOperation(value = "动态参数",notes = "获取用户")
// 设置动态参数描述注解
@DynamicParameters(name = "map",properties = {
@DynamicParameter(name = "id",value = "id",example = "1",required =
true,dataTypeClass = Integer.class),
@DynamicParameter(name = "userName",value = "用户名",required =true),
@DynamicParameter(name = "mobile",value = "手机号"),
})
public User obj1( @RequestBody Map map){
User u = new User();
u.setUserName("danseek");
u.setMobile("13888888888");
return u;
}
@GetMapping("obj2")
@ApiOperation(value = "静态参数",notes = "获取用户")
// 设置参数描述注解
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "id", required = false, dataType =
"integer", paramType = "query"),
@ApiImplicitParam(name = "mobile", value = "手机号", required = false, dataType =
"string", paramType = "query"),
})
public User obj2(Integer id,String mobile){
User u = new User();
u.setId(id);
u.setMobile(mobile);
u.setUserName("danseek");
u.setMobile("13888888888");
return u;
}
}
@ApiModelProperty给实体类参数加上注释
package com.danseek.demo.entity;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.experimental.Accessors;
/**
* 用户表
* @author danseek
* @CreateTime: 2020-10-23 15:25
*/
@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
public class User {
/**
* 用户ID
*/
@ApiModelProperty(value = "用户id",example = "1",required = false)
private Integer id;
/**
* 登录用户名
*/
@ApiModelProperty(value = "用户名",example = "admin",required = false)
private String userName;
/**
* 密码
*/
@ApiModelProperty(value = "密码",example = "123456",required = false)
private String password;
/**
* 登录者名字
*/
@ApiModelProperty(value = "用户姓名",example = "张三",required = false)
private String realName;
/**
* 登录者手机
*/
@ApiModelProperty(value = "手机",example = "13899999999",required = false)
private String mobile;
}
如图，中文描述都是用注解配的
如果需要在所有请求参数中配置token，设置globalOperationParameters即可
@Bean
public Docket createRestApi() {
ParameterBuilder parameterBuilder=new ParameterBuilder();
List<Parameter> parameters= Lists.newArrayList();
parameterBuilder.name("token").description("token令牌").modelRef(new ModelRef("String"))
.parameterType("header")
.required(true).build();
parameters.add(parameterBuilder.build());
return new Docket(DocumentationType.SWAGGER_2)
.useDefaultResponseMessages(true)
.groupName("前后端接⼝⽂档")
.apiInfo(apiInfo())
.select()
//选择哪些路径和API会生成document
.apis(RequestHandlerSelectors.basePackage("com.jassonsoft.admin.controller"))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(parameters);
}
文档中会显示
其他
1、隐藏某个请求参数使用@ApiIgnore注解在参数上
@ApiOperation(value = "文件上传")
@ApiImplicitParams({
@ApiImplicitParam(name = "file", value = "文件流对象",paramType="form", required = true,dataType = "__File"),
@ApiImplicitParam(name = "md5FileName", value = "文件名称",paramType="query", required = true)}
)
@RequestMapping(value = "uploadFile", method = RequestMethod.POST)
public ResponseVo uploadBanners(@ApiIgnore HttpServletRequest request, @ApiIgnore MultipartHttpServletRequest multipartReq){
ResponseVo responseVo = new ResponseVo();
.....
}
这时需要使用@ApiImplicitParam 注解隐式地声明接口参数，否则页面不会显示参数
2、接口排序
@ApiSort(value = 5)：给接口排序
@ApiOperationSupport(order = 1)：给接口里面的方法排序
@ApiIgnore()：接口或方法不在页面显示
@Api(value = "数据分析",tags = "数据分析")
@ApiSort(value = 5)
@Slf4j
@RestController
@RequestMapping("/analysis")
public class AnalysisDataController extends BaseController{
@ApiOperationSupport(value = "消息查询统计")
@ApiSupport(order = 1)
@RequestMapping(value = "getMessageQueryStatistics", method = RequestMethod.POST)
public ResponseVo<Page> getMessageQueryStatistics(HttpServletRequest request, @RequestBody Map map) {
....
}
}