knife4j-Swagger生成Api文档的增强解决方案

目录

介绍

引用

Api文档的增强

开启增强模式 yml

访问权限

接口、分组排序 

过滤请求参数

 包含请求参数

禁用调试功能

页面路径冲突解决

knife4j 为 Java MVC 框架生成 Api 文档，是为Java MVC框架集成Swagger生成Api文档的增强解决方案，,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍! 官方参考文档，描述很全面

介绍

更名后主要专注的方面：

• 前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活
• 提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分

特点：

• 简洁：基于左右菜单式的布局方式,是更符合国人的操作习惯吧.文档更清晰...
• 个性化配置：个性化配置项,支持接口地址、接口description属性、UI增强等个性化配置功能...
• 增强：接口排序、Swagger资源保护、导出Markdown、参数缓存众多强大功能...

开源仓库：

• Github

https://github.com/xiaoymin/swagger-bootstrap-ui
           

• 码云

https://gitee.com/xiaoym/knife4j
           

引用

不使用增强功能,纯粹换一个swagger的前端皮肤，这种情况是最简单的,你项目结构下无需变更

可以直接引用swagger-bootstrap-ui的最后一个版本1.9.6或者使用knife4j-spring-ui

老版本引用

<!--在引用时请在maven中央仓库搜索最新版本号-->

<dependency>    
  <groupId>com.github.xiaoymin</groupId>    
  <artifactId>swagger-bootstrap-ui</artifactId>    
  <version>1.9.6</version>
</dependency>
           

新版本引用

<dependency>    
  <groupId>com.github.xiaoymin</groupId>    
  <artifactId>knife4j-spring-ui</artifactId>    
  <version>${lastVersion}</version>
</dependency>
           

• Spring Boot项目单体架构使用增强功能

在Spring Boot单体架构下,knife4j提供了starter供开发者快速使用

<dependency>    
  <groupId>com.github.xiaoymin</groupId>    
  <artifactId>knife4j-spring-boot-starter</artifactId>    
  <version>${knife4j.version}</version>
</dependency>
           

该包会引用所有的knife4j提供的资源，包括前端Ui的jar包，2020-11更新到3.0.2

• Spring Cloud微服务架构

在Spring Cloud的微服务架构下,每个微服务其实并不需要引入前端的Ui资源,因此在每个微服务的Spring Boot项目下,引入knife4j提供的微服务starter

<dependency>    
  <groupId>com.github.xiaoymin</groupId>    
  <artifactId>knife4j-micro-spring-boot-starter</artifactId>    
  <version>${knife4j.version}</version>
</dependency>
           

在网关聚合文档服务下,可以再把前端的ui资源引入

<dependency>    
   <groupId>com.github.xiaoymin</groupId>    
   <artifactId>knife4j-spring-boot-starter</artifactId>    
   <version>${knife4j.version}</version>
</dependency>
           

Api文档的增强

文档： Spring Boot 项目使用knife4j

虽然文档都有，还是忍不住摘一些自己用到的方法 ->->

开启增强模式 yml

在以前的版本中,开发者需要在配置文件中手动使用

@EnableKnife4j

来使用增强，自2.0.6版本后,只需要在配置文件中配置

knife4j.enable=true

即可不在使用注解

knife4j:
  enable: true
           

访问权限

屏蔽所有Swagger的相关资源

knife4j:
  # 开启增强配置 
  enable: true
　# 开启生产环境屏蔽
  production: true
           

访问页面加权控制-Basic认证

knife4j:
  # 开启增强配置 
  enable: true
　# 开启Swagger的Basic认证功能,默认是false
  basic:
      enable: true
      # Basic认证用户名
      username: test
      # Basic认证密码
      password: 123
           

接口、分组排序 

接口排序配置在接口上

@ApiOperationSupport(order = 33)
@ApiOperation(value = "忽略参数值-Form类型")
@PostMapping("/ex")
public Rest<LongUser> findAll(LongUser longUser) {
    Rest<LongUser> r=new Rest<>();
    r.setData(longUser);
    return r;
}
           

分组在类上

@Api(tags = "2.0.3版本-20200312")
@ApiSupport(order = 284)
@RestController
@RequestMapping("/api/nxew203")
public class Api203Constroller {
    
    
}
           

过滤请求参数

- - 直接使用实体的属性名称进行参数忽略

表单

@ApiOperation(value = "新增Model接口1")
@ApiOperationSupport(ignoreParameters = {"id","orderDate.id"})
@PostMapping("/insertMode1l")
public Rest<UptModel> insertModel1(UptModel uptModel){
    Rest<UptModel> r =new Rest<>();
    r.setData(uptModel);
    return r;
}
           

JSON参数

@ApiOperation(value = "新增Model接口")
@ApiOperationSupport(ignoreParameters = {"uptModel.id","uptModel.name","uptModel.orderDate.id"})
@PostMapping("/insertModel")
public Rest<UptModel> insertModel(@RequestBody UptModel uptModel){
    Rest<UptModel> r =new Rest<>();
    r.setData(uptModel);
    return r;
}
           

 包含请求参数

- - 强制包含要显示的参数.去除多余的参数显示

表单

@ApiOperationSupport(order = 40,includeParameters = {"ignoreLabels","longUser.ids"})
@ApiOperation(value = "包含参数值-Form类型1")
@PostMapping("/ex1c")
public Rest<IgnoreP1> findAllc12(IgnoreP1 ignoreP1) {
    Rest<IgnoreP1> r=new Rest<>();
    r.setData(ignoreP1);
    return r;
}
           

JSON参数

@ApiOperationSupport(order = 42,includeParameters = {"ignoreP1.ignoreLabels.code","ignoreP1.longUser.ids"})
@ApiOperation(value = "包含参数值-JSON类型1")
@PostMapping("/exc3")
public Rest<IgnoreP1> findAllc3(@RequestBody IgnoreP1 ignoreP1) {
    Rest<IgnoreP1> r=new Rest<>();
    r.setData(ignoreP1);
    return r;
}
           

禁用调试功能

knife4j:
  enable: true
  setting:
    enableDebug: false
           

页面路径冲突解决

Springboot页面与swagger页面冲突解决

@Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //映射static路径的请求到static目录下
        // 静态资源访问路径和存放路径配置
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
        // swagger访问配置
//        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/","classpath:/META-INF/resources/webjars/");
        // knife4j访问配置
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/","classpath:/META-INF/resources/webjars/");
    }
           

FAQ其他一些问题：https://doc.xiaominfo.com/faq/swagger-des-not-found.html