Swagger–基础–03–集成Springboot3–Knife4j

1、Knife4j介绍

Knife4j 是一个集Swagger2和OpenAPI3为一体的增强解决方案，帮助开发者快速聚合使用OpenAPI规范。

官网地址：https://doc.xiaominfo.com/

1.1、核心特性

1.1.1、基础特性

• 兼容 OpenAPI 2.0
• 兼容 OpenAPI 3.0
• 增强扩展功能

1.1.2、UI 组件增强

• 自定义文档
• 动态参数调试
• 国际化支持 (I18n)
• 接口排序
• 文档导出

1.1.3、自动注入支持

• 基于 Springfox 框架 + Swagger2 规范的自动注入 starter
• 基于 Springdoc-openapi + OAS3 规范的自动注入 starter

1.1.4、网关聚合

提供对主流网关组件的统一聚合 OpenAPI 接口文档的解决方案

1.2、框架适配

• 适配兼容Spring MVC
• 适配兼容Spring Boot 2.2、2.3、2.4、2.5、2.6、2.7、3.0
• 适配兼容Spring WebFlux
• 基于SpringFox2.x版本提供Swagger2规范的增强扩展
• 基于Springdoc-openapi项目提供OAS3规范的增强扩展

1.3、云原生

• 提供基于K8S+Docker的云原生的聚合OpenAPI文档的解决方案
• 简化Knife4j的使用及学习成本，一键部署&集成&使用

2、快速接入

添加一个maven依赖就可以

<!-- knife4j -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

3、常用功能

地址：域名/doc.html

3.1、主页

3.2、接口–文档

3.3、接口–调试

3.4、接口–Open

3.5、接口–Script

4、配置属性

knife4j:
  enable: true
  documents:
    -
      group: 2.X版本
      name: 接口签名
      locations: classpath:sign/*
  setting:
    language: zh-CN
    enable-swagger-models: true
    enable-document-manage: true
    swagger-model-name: 实体类列表
    enable-version: false
    enable-reload-cache-parameter: false
    enable-after-script: true
    enable-filter-multipart-api-method-type: POST
    enable-filter-multipart-apis: false
    enable-request-cache: true
    enable-host: false
    enable-host-text: 192.168.0.193:8000
    enable-home-custom: true
    home-custom-path: classpath:markdown/home.md
    enable-search: false
    enable-footer: false
    enable-footer-custom: true
    footer-custom-content: Apache License 2.0 | Copyright  2019-[浙江八一菜刀股份有限公司](https://gitee.com/xiaoym/knife4j)
    enable-dynamic-parameter: false
    enable-debug: true
    enable-open-api: false
    enable-group: true
  cors: false
  production: false
  basic:
    enable: false
    username: test
    password: 12313

各个配置属性说明如下：

属性	默认值	说明值
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.enable-after-script	true	调试Tab是否显示AfterScript功能,默认开启
knife4j.setting.language	zh-CN	Ui默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)
knife4j.setting.enable-swagger-models	true	是否显示界面中SwaggerModel功能
knife4j.setting.swagger-model-name	Swagger Models	重命名SwaggerModel名称,默认
knife4j.setting.enable-document-manage	true	是否显示界面中"文档管理"功能
knife4j.setting.enable-reload-cache-parameter	false	是否在每个Debug调试栏后显示刷新变量按钮,默认不显示
knife4j.setting.enable-version	false	是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点
knife4j.setting.enable-request-cache	true	是否开启请求参数缓存
knife4j.setting.enable-filter-multipart-apis	false	针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址
knife4j.setting.enable-filter-multipart-api-method-type	POST	具体接口的过滤类型
knife4j.setting.enable-host	false	是否启用Host
knife4j.setting.enable-host-text	false	HOST地址
knife4j.setting.enable-home-custom	false	是否开启自定义主页内容
knife4j.setting.home-custom-path		主页内容Markdown文件路径
knife4j.setting.enable-search	false	是否禁用Ui界面中的搜索框
knife4j.setting.enable-footer	true	是否显示Footer
knife4j.setting.enable-footer-custom	false	是否开启自定义Footer
knife4j.setting.footer-custom-content	false	自定义Footer内容
knife4j.setting.enable-dynamic-parameter	false	是否开启动态参数调试功能
knife4j.setting.enable-debug	true	启用调试
knife4j.setting.enable-open-api	true	显示OpenAPI规范
knife4j.setting.enable-group	true	显示服务分组