乐趣区

关于springboot:笑小枫的SpringBoot系列二基于swagger2的knife4j接口文档

jiezi

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 的依赖包，代码如下：👇

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

👉第二步：创立 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 拜访

接口调试：

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, 如下图：

更多功能，请参考官网文档：https://doc.xiaominfo.com/knife4j/

退出移动版