笑小枫的SpringBoot系列二基于swagger的knife4j接口文档

　　2 配置后端接口2.1 什么是knife4j
　　Knife4j 的前身是swagger-bootstrap-ui ,前身swagger-bootstrap-ui 是一个纯swagger-ui 的ui 皮肤项目
　　一开始项目初衷是为了写一个增强版本的swagger的前端ui,但是随着项目的发展,面对越来越多的个性化需求,不得不编写后端Java代码以满足新的需求,在 swagger-bootstrap-ui 的1.8.5~1.9.6版本之间,采用的是后端Java代码和Ui都混合在一个Jar包里面的方式提供给开发者使用.这种方式虽说对于集成swagger来说很方便,只需要引入jar包即可,但是在微服务架构下显得有些臃肿。
　　因此,项目正式更名为 knife4j ,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.
　　swagger-bootstrap-ui 的所有特性都会集中在knife4j-spring-ui 包中,并且后续也会满足开发者更多的个性化需求.
　　主要的变化是,项目的相关类包路径更换为 com.github.xiaoymin.knife4j 前缀,开发者使用增强注解时需要替换包路径
　　后端Java代码和ui包分离为多个模块的jar包,以面对在目前微服务架构下,更加方便的使用增强文档注解(使用SpringCloud微服务项目,只需要在网关层集成UI的jar包即可,因此分离前后端)
　　knife4j 沿用 swagger-bootstrap-ui 的版本号,第1个版本从1.9.6开始,关于使用方法,请参考文档。2.2 怎么使用knife4j
　　第一步：在maven项目的 pom.xml 中引入Knife4j的依赖包，代码如下：     com.github.xiaoymin     knife4j-spring-boot-starter     2.0.7 
　　第二步：创建Swagger配置依赖，代码如下： package com.maple.demo.config;  import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;  /**  * @author 笑小枫  * @date 2022/6/28  */ @Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration {      @Bean(value = ＂example＂)     public Docket example() {         return new Docket(DocumentationType.SWAGGER_2)                 .apiInfo(new ApiInfoBuilder()                         .title(＂笑小枫实例演示接口＂)                         .description(＂笑小枫实例演示接口＂)                         .termsOfServiceUrl(＂http://127.0.0.1:6666＂)                         .contact(new Contact(＂笑小枫＂, ＂https://www.xiaoxiaofeng.site＂, ＂zfzjava@163.com＂))                         .version(＂1.0＂)                         .build())                 //分组名称                 .groupName(＂演示实例接口＂)                 .select()                 //这里指定Controller扫描包路径                 .apis(RequestHandlerSelectors.basePackage(＂com.maple.demo.controller＂))                 .paths(PathSelectors.any())                 .build();     } }
　　第三步：创建一个Controller package com.maple.demo.controller;  import io.swagger.annotations.Api; import io.swagger.annotations.ApiModelProperty; import io.swagger.annotations.ApiOperation; import lombok.Data; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController;  /**  * @author zhangfuzeng  * @date 2022/6/30  */ @Api(tags = ＂实例演示-Knife4j接口文档＂) @RestController @RequestMapping(＂/example＂) public class TestKnife4jController {          @ApiOperation(value = ＂Knife4j接口文档演示＂)     @GetMapping(＂/testKnife4j＂)     public Test testKnife4j(Test param) {         Test test = new Test();         test.setName(＂笑小枫＂);         test.setAge(18);         test.setRemark(＂大家好，我是笑小枫，喜欢我的小伙伴点个赞呗，欢迎访问我的个人博客：http://www.xiaoxiaofeng.site＂);         return test;     }      @Data     static class Test {         @ApiModelProperty(value = ＂姓名＂)         private String name;          @ApiModelProperty(value = ＂年龄＂)         private Integer age;          @ApiModelProperty(value = ＂描述＂)         private String remark;     } } 2.3 看下页面效果
　　项目启动后，在浏览器输入http://127.0.0.1:6666/doc.html访问
　　image-20220711165333302
　　接口调试：
　　image-20220711165425505 2.4 增强模式
　　Knife4j自2.0.6版本开始,将目前在Ui界面中一些个性化配置剥离,开发者可以在后端进行配置，并且提供的knife4j-spring-boot-strater组件自动装载
　　spring.factories配置如下： # Auto Configure org.springframework.boot.autoconfigure.EnableAutoConfiguration= com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration
　　在Spring Boot配置文件中,完整的配置如下: knife4j:   enable: true   documents:     -       group: 2.X版本       name: 接口签名       locations: classpath:sign/*   setting:     language: zh-CN     enableSwaggerModels: true     enableDocumentManage: true     swaggerModelName: 实体类列表     enableVersion: false     enableReloadCacheParameter: false     enableAfterScript: true     enableFilterMultipartApiMethodType: POST     enableFilterMultipartApis: false     enableRequestCache: true     enableHost: false     enableHostText: 192.168.0.193:8000     enableHomeCustom: true     homeCustomLocation: classpath:markdown/home.md     enableSearch: false     enableFooter: false     enableFooterCustom: true     footerCustomContent: Copyright  2022-[笑小枫](https://www.xiaoxiaofeng.site)     enableDynamicParameter: false     enableDebug: true     enableOpenApi: false     enableGroup: true   cors: false   production: false   basic:     enable: false     username: test     password: 123123
　　在以前的版本中,开发者需要在配置文件中手动使用 @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
　　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进行赋值
　　示例代码如下： package com.maple.demo.config;  import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;  /**  * @author 笑小枫  * @date 2022/6/28  */ @Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration {     /*引入Knife4j提供的扩展类*/     private final OpenApiExtensionResolver openApiExtensionResolver;      @Autowired     public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {         this.openApiExtensionResolver = openApiExtensionResolver;     }      @Bean(value = ＂example＂)     public Docket example() {         String groupName=＂演示实例接口＂;         return new Docket(DocumentationType.SWAGGER_2)                 .apiInfo(new ApiInfoBuilder()                         .title(＂笑小枫实例演示接口＂)                         .description(＂笑小枫实例演示接口＂)                         .termsOfServiceUrl(＂http://127.0.0.1:6666＂)                         .contact(new Contact(＂笑小枫＂, ＂http://www.xiaoxiaofeng.site＂, ＂zfzjava@163.com＂))                         .version(＂1.0＂)                         .build())                 //分组名称                 .groupName(groupName)                 .select()                 //这里指定Controller扫描包路径                 .apis(RequestHandlerSelectors.basePackage(＂com.maple.demo.controller＂))                 .paths(PathSelectors.any())                 .build()              //赋予插件体系                 .extensions(openApiExtensionResolver.buildExtensions(groupName));     } }
　　buildExtensions 方法需要传入分组名称,该分组名称主要是为了区分开发者在构建自定义文档时，在不同的Docket逻辑分组下进行区别显示。
　　OpenApiExtensionResolver 辅助类需要配置knife4j.enable=true 才能自动@Autowired
　　增强效果开启后,在最终调用接口时，Knife4j会添加扩展属性 x-openapi ,如下图：
　　image-20220630132424363
　　更多功能，请参考官方文档：https://doc.xiaominfo.com/knife4j/