Spring Cloud 学习笔记十五：搭建微服务工程之Knife4j 介绍及使用

目录

Knife4j 介绍及使用

---

Knife4j 介绍及使用

Knife4j的前身是swagger-bootstrap-ui，前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目。具体介绍见官方文档 https://doc.xiaominfo.com/knife4j/documentation/description.html 。

在pom.xml中引入 Knife4j 的依赖包，代码如下：

<!-- knife4j导出swagger文档 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

在 Swagger3Config配置类添加 @EnableKnife4j注解：

@Configuration
@EnableOpenApi
@EnableKnife4j
public class Swagger3Config {
...
}

重启服务，访问 http://localhost:8081/doc.html，可以看到界面。

增强模式

Knife4j 自 2.0.6 版本开始，将目前在 UI 界面中一些个性化配置剥离，开发者可以在后端进行配置。

在配置文件中，完整的配置如下:

knife4j:
  enable: true
  documents:
    -
      group: 1.x
      name: 接口签名
      locations: classpath:/*
  setting:
    language: zh-CN
    enableSwaggerModels: true
    enableDocumentManage: true
    swaggerModelName: 实体类列表
    enableVersion: false
    enableReloadCacheParameter: false
    enableAfterScript: true
    enableFilterMultipartApiMethodType: POST
    enableFilterMultipartApis: false
    enableRequestCache: true
    enableHost: false
    enableHostText: localhost:8081
    enableHomeCustom: false
    homeCustomLocation: classpath:markdown/home.md
    enableSearch: true
    enableFooter: false
    enableFooterCustom: true
    footerCustomContent: Apache License 2.0 | Copyright  2021-[stary1993码云](https://gitee.com/stary1993)
    enableDynamicParameter: false
    enableDebug: true
    enableOpenApi: true
    enableGroup: true
  cors: false
  production: false
  basic:
    enable: true
    username: admin
    password: 123456

在以前的版本中，开发者需要在配置文件中手动使用 @EnableKnife4j 来使用增强，自 2.0.6 版本后，只需要在配置文件中配置 knife4j.enable=true 即可不在使用注解。

注意：要使用 Knife4j 提供的增强，knife4j.enable=true必须开启

各个配置属性说明如下：

属性	默认值	说明值
knife4j.enable	false	是否开启 Knife4j 增强模式
knife4j.cors	false	是否开启一个默认的跨域配置，该功能配合自定义 Host 使用
knife4j.production	false	是否开启生产环境保护策略,详情参考文档
knife4j.basic		对 Knife4j 提供的资源提供 BasicHttp 校验，保护文档
knife4j.basic.enable	false	关闭 BasicHttp 功能
knife4j.basic.username		basic 用户名
knife4j.basic.password		basic 密码
knife4j.documents		自定义文档集合，该属性是数组
knife4j.documents.group		所属分组
knife4j.documents.name		类似于接口中的 tag，对于自定义文档的分组
knife4j.documents.locations		markdown文件路径，可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md)
knife4j.setting		前端 UI 的个性化配置属性
knife4j.setting.enableAfterScript	true	调试 Tab 是否显示 AfterScript 功能，默认开启
knife4j.setting.language	zh-CN	UI 默认显示语言,目前主要有两种：中文(zh-CN)、英文(en-US)
knife4j.setting.enableSwaggerModels	true	是否显示界面中 SwaggerModel 功能
knife4j.setting.swaggerModelName	Swagger Models	重命名 SwaggerModel 名称，默认
knife4j.setting.enableDocumentManage	true	是否显示界面中"文档管理"功能
knife4j.setting.enableReloadCacheParameter	false	是否在每个 Debug 调试栏后显示刷新变量按钮,默认不显示
knife4j.setting.enableVersion	false	是否开启界面中对某接口的版本控制,如果开启，后端变化后 UI 界面会存在小蓝点
knife4j.setting.enableRequestCache	true	是否开启请求参数缓存
knife4j.setting.enableFilterMultipartApis	false	针对 RequestMapping 的接口请求类型，在不指定参数类型的情况下，如果不过滤，默认会显示 7 个类型的接口地址参数，如果开启此配置，默认展示一个 Post 类型的接口地址
knife4j.setting.enableFilterMultipartApiMethodType	POST	具体接口的过滤类型
knife4j.setting.enableHost	false	是否启用 Host
knife4j.setting.enableHomeCustom	false	是否开启自定义主页内容
knife4j.setting.homeCustomLocation		主页内容 Markdown 文件路径
knife4j.setting.enableSearch	false	是否禁用 UI 界面中的搜索框
knife4j.setting.enableFooter	true	是否显示 Footer，如果要自定义的话该属性必须设置为false，否则不会生效
knife4j.setting.enableFooterCustom	false	是否开启自定义 Footer
knife4j.setting.footerCustomContent	false	自定义 Footer 内容
knife4j.setting.enableDynamicParameter	false	是否开启动态参数调试功能
knife4j.setting.enableDebug	true	启用调试
knife4j.setting.enableOpenApi	true	显示 OpenAPI 规范
knife4j.setting.enableGroup	true	显示服务分组

关于个性化文档(knife4j.documents)以及个性化设置(knife4j.setting)，有一些细微的区别，开发者在配置文件中进行配合好后，还需要在创建Docket对象时调用Knife4j提供的扩展Extesions进行赋值，示例代码如下：

/*引入Knife4j提供的扩展类*/
@Autowired
private OpenApiExtensionResolver openApiExtensionResolver;
/**
     * 创建 API 1.x
     */
    @Bean
    public Docket createRestApi1() {
        String groupName = "1.x";
        return new Docket(DocumentationType.OAS_30)
               ...
                //赋予插件体系
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
    }

具体其他使用设置参考官方文档：https://doc.xiaominfo.com/knife4j/documentation/。