spring boot java SpringBoot 整合knife4j

文章目录

SpringBoot 整合knife4j引入knife4j注解案例knife4j增强功能接口添加作者资源屏蔽访问页面加权控制接口排序分组排序请求参数缓存过滤请求参数禁用调试禁用搜索框

SpringBoot 整合knife4j

Knife4j是一款基于Swagger 2的在线API文档框架

在Spring Boot中，使用此框架时，需要：

- 添加依赖

- 在配置文件（`application.properties`）中开启增强模式

- 编写配置类（代码相对固定，建议CV）

引入knife4j

添加依赖

com.github.xiaoymin

knife4j-spring-boot-starter

3.0.3

创建 Swagger 配置依赖

package com.yolo.knife4j.config;

import io.swagger.annotations.Api;

import lombok.extern.slf4j.Slf4j;

import org.springframework.beans.factory.annotation.Value;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.context.annotation.Import;

import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;

import springfox.documentation.builders.*;

import springfox.documentation.service.*;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Slf4j

@Configuration

@EnableSwagger2WebMvc

// 对JSR303提供支持

@Import(BeanValidatorPluginsConfiguration.class)

public class Knife4jConfig {

@Value("${spring.application.name}")

private String applicationName;

@Bean

public Docket defaultApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.groupName(applicationName)

.select()

// 添加@Api注解才显示

.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

// 这里指定Controller扫描包路径

// .apis(RequestHandlerSelectors.basePackage("com.yolo"))

.paths(PathSelectors.any())

.build();

}

/**

* swagger-api接口描述信息

*/

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("API文档")

.description("API文档")

.contact(

new Contact(

"yolo",

"https://gitee.com/huanglei1111",

"2936412130@qq.com"

)

)

.version("1.0.0")

.build();

}

}

application.yml配置文件

# https://doc.xiaominfo.com/knife4j

knife4j:

# 开启增强配置

enable: true

# 是否开启生产环境屏蔽 true:关闭swagger，false:开启swagger

production: false

basic:

# 是否开启认证

enable: false

# Basic认证用户名

username: admin

# Basic认证密码

password: 123456

spring:

application:

name: test-knife4j

注解

@Api(tags = {“用户操作”})

加在controller类上

tags表示该类的标签，在页面会独立显示一个菜单

@ApiOperation(value = “保存用户”, notes = “保存时，ID由数据库生成，无需填写，有则忽略”, tags = “保存”)

加在相应的请求处理方法上

value表示该方法的说明

notes相当于对该方法的详细说明，也就是更加完整的描述

tags 表示标签，，在页面会独立显示一个菜单

@ApiImplicitParam(name = “id”, value = “用户ID”, defaultValue = “1”)

方法只有一个基本类型参数时加在方法上。方法有多个参数时加在@ApiImplicitParams内

name 参数中属性的名字

value 对这个属性的描述

defaultValue 默认值，这个还是有必要填写的，在页面进行请求时，会自动填充

@ApiImplicitParams(value = {})

用在请求方法上

这个注解必须和@ApiImplicitParam配合使用

当请求方法中的请求参数很多的时候，例如saveUser(String username, Integer age, Date birthday, String phone)

@ApiParam(value = “当前页”, defaultValue = “1”)

加在请求方法的普通参数上

value的值是对该参数的说明

与@ApiImplicitParam使用的效果等同，根据个人喜好进行使用

@ApiModel(value = “用户信息”)

加在请求方法的对象类上

value 对该对象参数的描述

例如有一个请求方法save(UserDTO userDTO), 则需要加在UserDTO这个类上面(可以参照下面的示例)

@ApiModelProperty(value = “用户ID”, example = “1”)

加在请求方法的参数对象的属性上

value 对该属性的描述

example 属性的示例值，在页面会自动填充该值

@ApiIgnore：注解类、参数、方法，注解后将不在Swagger UI中显示

案例

package com.yolo.knife4j.controller;

import cn.hutool.core.collection.ListUtil;

import com.yolo.knife4j.base.ResultVo;

import com.yolo.knife4j.dto.UserAddRequest;

import com.yolo.knife4j.vo.StudentVO;

import com.yolo.knife4j.vo.UserVO;

import io.swagger.annotations.*;

import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;

import java.util.Date;

@ApiResponses(value = {

@ApiResponse(code = 200, message = "接口返回成功状态"),

@ApiResponse(code = 500, message = "接口返回未知错误，请联系开发人员调试")

})

@Api(tags = "用户")

@RestController

@RequestMapping("/user")

public class UserController {

@ApiOperation(value = "保存用户", notes = "简单传参")

@PostMapping("/add")

public ResultVo