springfox-swagger+knife4j

---

• 本人最近在找工作，有推荐的小伙伴私我，不胜感激。

前言

• 内容参考ruoyi框架的配置类+knife4j官网的介绍文档

knife4j介绍

• 官网：https://doc.xiaominfo.com/docs/features/enhance
• knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，前身是swagger-bootstrap-ui，取名knife4j是希望它能像一把匕首一样小巧、轻量、功能强悍
• 早期，swagger-boostrap-ui是1.x版本，如今swagger-bootsrap-ui到2.x，同时也更改名字Knife4j

knife4j优点

• 基于左右菜单式的布局方式，更符合国人的操作习惯
• 添加接口搜索功能
• 支持离线文档导出Markdown、Html、Word、OpenApi的json

一、依赖

<!-- springfox-swagger -->
<!--
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
-->
<!-- knife4j,该依赖包含springfox-boot-starter-3.0,所以无需再手动引入swagger相关依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

二、配置文件

#knife4j
knife4j:
  #是否开启Knife4j增强模式,默认false,要使用Knife4j提供的增强,则必须开启
  #在以前的版本中,开发者需要在配置文件中手动使用@EnableKnife4j来使用增强，自2.0.6版本后,只需要在配置文件中配置enable=true即可不在使用注解
  enable: true
  #自定义文档集合，该属性是数组
  #documents:
    #-
      #所属分组
      #group: 2.X版本
      #name: 接口签名
      #locations: classpath:sign/*
  #前端UI的个性化配置
  setting:
    #Ui默认显示语言,目前主要有两种:中文(zh-CN)默认、英文(en-US),UI界面上也可以手动切换语言
    #language: zh-CN
    #是否开启SwaggerModel菜单,默认true
    #enableSwaggerModels: true
    #自定义左侧SwaggerModel菜单名称
    swaggerModelName: 实体类列表
    #是否显示UI界面"文档管理"菜单,默认true
    #enableDocumentManage: true
    #是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点,默认false
    #enableVersion: false
    #是否在每个Debug调试栏后显示刷新变量按钮,默认false
    #enableReloadCacheParameter: false
    #调试Tab是否显示AfterScript功能,默认true
    #enableAfterScript: true
    #具体接口的过滤类型,默认POST
    #enableFilterMultipartApiMethodType: POST
    #是否开启请求参数缓存,默认true
    #enableRequestCache: true
    #是否启用Host,默认false
    #enableHost: false
    #enableHostText: 192.168.0.193:8000
    #是否开启自定义主页内容,默认false
    #enableHomeCustom: false
    #主页内容Markdown文件路径
    #homeCustomLocation: classpath:markdown/home.md
    #是否禁用Ui界面中的搜索框,默认false
    #enableSearch: false
    #是否显示knife4j默认的Footer,默认true(Apache License 2.0 | Copyright  2019-[浙江八一菜刀股份有限公司](https://gitee.com/xiaoym/knife4j))
    enableFooter: false
    #是否显示UI界面自定义Footer内容,默认false
    enableFooterCustom: true
    #自定义的Footer内容
    footerCustomContent: kimi的swagger接口文档
    #是否开启动态参数调试功能,默认false
    #enableDynamicParameter: false
    #是否启用调试功能,默认true
    #enableDebug: true
    #显示OpenAPI规范,默认true
    #enableOpenApi: false
    #显示服务分组,默认true
    #enableGroup: true
  #是否开启一个默认的跨域配置,该功能配合自定义Host使用,默认false
  #cors: false
  #是否开启生产环境保护策略,默认false
  #production: false
  #对Knife4j提供的资源提供BasicHttp校验,保护文档,就是访问UI页面时需要输入用户名/密码
  basic:
    #是否开启,默认false
    enable: true
    #basic用户名
    username: kimi
    #basic密码
    password: 99999
    
#swagger
swagger:
  #是否开启,生产环境不需要展示接口UI可关闭
  enabled: true
  #组名
  group-name: springfox-swagger项目组
  #标题
  title: springfox-swagger模块接口
  #描述
  description: springfox-swagger模块接口文档
  #版本
  version: 1.0
  #许可证
  license: Powered By kimi
  #许可证URL
  license-url: https://kimi.vip
  #作者信息
  contact:
    name: kimi
    url: kimi
    email: kimi@qq.com

三、swagger配置类

/**
 * swagger配信信息映射类
 * @author kimi
 * @Date 2022-08-13
 */
@Data
public class SwaggerProperties{

    /** 是否开启swagger */
    private Boolean enabled;

    /** 组名 */
    private String groupName="";

    /** 标题 */
    private String title = "";

    /** 描述 */
    private String description = "";

    /** 版本 */
    private String version = "";

    /** 许可证 */
    private String license = "";

    /** 许可证URL */
    private String licenseUrl = "";

    /** 联系人信息 */
    private Contact contact = new Contact();

    /** 全局统一鉴权配置 */
    private Authorization authorization = new Authorization();

    @Data
    public static class Contact{

        /** 联系人 */
        private String name = "";
        
        /** 联系人url */
        private String url = "";
        
        /** 联系人email */
        private String email = "";

    }

    @Data
    public static class Authorization{

        /** 鉴权策略ID，需要和SecurityReferences ID保持一致 */
        private String name = "";

        /** 需要开启鉴权URL的正则 */
        private String authRegex = "^.*$";

        /** 鉴权作用域列表 */
        private List<AuthorizationScope> authorizationScopeList = new ArrayList<>();

    }

    @Data
    public static class AuthorizationScope{
        
        /** 作用域名称 */
        private String scope = "";

        /** 作用域描述 */
        private String description = "";

    }
}
    
/**
 * swagger配置类
 * @author kimi
 * @Date 2022/8/13
 */
@Configuration
public class SwaggerAutoConfiguration{

  /**
   * 引入Knife4j提供的扩展类
   * 个性化文档配置knife4j.documents、个性化设置knife4j.setting 就是通过该扩展类生效
   */
  @Autowired
  private OpenApiExtensionResolver openApiExtensionResolver;

  /**
   * 读取配置文件中swagger的配置信息映射到SwaggerProperties的Bean
   * @return
   */
  @Bean
  @ConfigurationProperties("swagger")
  @ConditionalOnMissingBean
  public SwaggerProperties swaggerProperties(){
    return new SwaggerProperties();
  }

  @Bean
  public Docket api(SwaggerProperties swaggerProperties){
    final String groupName="springfox-swagger项目组";
    //swagger版本3.0
    return new Docket(DocumentationType.OAS_30)
      //是否开启,默认true
      .enable(swaggerProperties.getEnabled())
      //分组名称,默认default,若需要多个分组则需要返回多个Docket的Bean,分别设置groupName(多人合作时可能每个开发者配置自己的分组)
      .groupName(swaggerProperties.groupName())
      //摘要信息,默认ApiInfo.DEFAULT(new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()))
      .apiInfo(apiInfo(swaggerProperties))
      //配置扫描的接口,默认ApiSelector.DEFAULT
      .select()
        /**
         * 扫描的接口
         * RequestHandlerSelectors.any()扫描全部
         * RequestHandlerSelectors.none()不扫描任何接口
         * RequestHandlerSelectors.withClassAnnotation(Api.class)扫描带有@Api注解的类
         * RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage())扫描接口的根包
         * RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)扫描带有@ApiOperation注解的方法,最灵活
         */
        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        /**
         * 扫描的接口路径
         * PathSelectors.any()扫描所有路径
         * PathSelectors.none()不扫描任何路径
         * PathSelectors.regex()扫描匹配正则表达式的路径
         */
        .paths(PathSelectors.any())
        .build()
      //赋予knife4j插件体系
      .extensions(openApiExtensionResolver.buildExtensions(groupName))
      //安全认证
      //.securitySchemes(securitySchemes())
      //安全上下文
      //.securityContexts(securityContexts())
      //设置请求的统一前缀
      .pathMapping("/");
  }

  /**
   * 安全认证
   *  swagger可以设置访问token,这里指定token通过Authorization头请求头传递,在页面UI上然后通过认证按钮输入token信息,注意这里不用加bearer前缀
   */
  private List<SecurityScheme> securitySchemes(){
    List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
    apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
    return apiKeyList;
  }

  /**
   * 安全上下文
   */
  private List<SecurityContext> securityContexts(){
    List<SecurityContext> securityContexts = new ArrayList<>();
    securityContexts.add(
      SecurityContext.builder()
        .securityReferences(defaultAuth())
        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
        .build());
    return securityContexts;
  }

  /**
   * 默认的全局鉴权策略
   *
   * @return
   */
  private List<SecurityReference> defaultAuth(){
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    List<SecurityReference> securityReferences = new ArrayList<>();
    securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
    return securityReferences;
  }

  /**
   * 添加摘要信息
   * 用来创建该API的基本信息，展示在文档的页面中
   *
   * @param swaggerProperties
   * @return
   */
  private ApiInfo apiInfo(SwaggerProperties swaggerProperties){
    return new ApiInfoBuilder()
      //标题
      .title(swaggerProperties.getTitle())
      //描述
      .description(swaggerProperties.getDescription())
      //许可证
      .license(swaggerProperties.getLicense())
      //许可证URL
      .licenseUrl(swaggerProperties.getLicenseUrl())
      //作者信息
      .contact(new Contact(swaggerProperties.getContact().getName(), swaggerProperties.getContact().getUrl(), swaggerProperties.getContact().getEmail()))
      //版本
      .version(swaggerProperties.getVersion())
      .build();
  }

四、swagger的拦截器配置

/**
 * swagger拦截器配置

 * @author kimi
 * @Date 2022/8/17
 */
@Configuration
public class SwaggerWebConfiguration implements WebMvcConfigurer{

  /**
   * 配置静态资源与请求地址映射,使得不对其进行拦截,并且能够快速找到
   * @param registry
   */
  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry){

    /** swagger-ui的静态资源与请求路径映射 */
    registry.addResourceHandler("/swagger-ui/**")
      .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
  }
}

五、访问

• swagger原生UI：ip:port/项目的context-path/swagger-ui/index.html
• knife4j的UI：ip:port/项目的context-path/doc.html
  

六、关闭

• 关闭接口文档的只需要将配置文件的swagger.enabled=false即可

七、注解

所有的注解只是对接口、接口参数、接口响应等等的描述而已，而不是不加这些注解就不会生成接口文档，即使不加这些注解swagger也会生成默认的接口文档描述

springfox-swagger的注解

• 提供了基础的文档解释注解

@Api
//类说明，用在请求的类上
    //属性
    String[] tags() default {""};//该类的描述，默认=类名，如UserController

@ApiOperation
//接口说明，用在请求的接口方法上
    //属性
    String value();//接口描述
    String notes() default "";//接口的详细描述
    String httpMethod() default "";//请求方法，不写则读取接口上的@GetMapping . . .来识别

@ApiImplicitParams
    //一组参数注解，用在请求的方法上，用于接口用注解（@RequestParam、@PathVariable）+多个参数接收请求参数的情况，用实体类接收无效
    //属性
    ApiImplicitParam[] value();
    @ApiImplicitParam
    //同上，只是单个参数用该注解即可
        属性
        String name() default "";//参数key
        String value() default "";//参数名
        String defaultValue() default "";//参数默认值
        boolean required() default false;//是否必选，不写则读取@RequestParam或者@PathVariable中的required
        boolean allowMultiple() default false;//是否为数组，这里=true，则dataType为数组的泛型
        String dataType() default "";//数据类型，String、Integer . . .，不写则读取参数前面的数据类型String username = String
        String paramType() default "";//参数类型
            header - @RequestHeader
            query - @RequestParam
            path - @PathVariable
            form - 表单数据
            
@ApiResponses
    //一组响应，用在请求方法上
    //属性
    ApiResponse[] value();//状态码对应的消息
        默认会提供200 - ok、401 - Unauthorized、
        403 - Forbidden、
        404 - Not Found
        属性
            int code();//状态码
            String message();//对应的消息
@ApiModel
    //用在请求参数、响应的实体上，用于接口用实体类接收 或 响应的情况
    //只要接口中包含实体类，无论是请求参数还是响应参数，无论加不加注解该实体都会出现在ui界面的Schemas中，加上这两个注解只是对该实体的描述
    //属性
    String value() default "";//实体描述，如响应实体，默认=实体类名，如AjaxResult
    String description() default "";//实体详细描述，如后端响应前端实体
    
@ApiModelProperty
    //用在实体类的属性上
    //属性
    String value() default "";//属性的描述
    String dataType() default "";//属性数据类型，不写则读取属性的数据类型，String username = String，即使是集合不写也能自动识别出来，写了反而不好使
    boolean required() default false;//属性是否必选

kni4j的注解

• 在springfox-swagger的基础上增加了增强的注解,补充了一些解释

@ApiSupport
//类说明，用在请求的类上
    //属性
    int order() default 2147483647; //Controller类接口文档的排序
    String author() default ""; //该类下所有接口的作者
@ApiOperationSupport
//接口说明，用在请求的接口方法上
    //属性
    int order() default 0; //接口在类中的排序
    String author() default ""; //接口作者,@ApiSupport和@ApiOperationSupport同时指定了作者，那么方法级别的@ApiOperationSupport优先级更高
    String[] ignoreParameters() default {}; //忽略实体类的属性
    String[] includeParameters() default {}; //包含实体类的属性
    //有时候我们新增实体和修改实体的接口会使用同一个对象作为请求参数，但是我们新增实体的时候并不需要id，而修改的时候会需要id，此时我们可以使用这两个属性来忽略id或者包含除id外的其它属性
    //若属性是多层次时：includeParameters={"uptModel.id"}