文章目录

• 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