标签：SpringBoot swagger2 knife4j knife4j-spring-boot-starter knife4j-spring-ui 自定义

knife4j-spring-ui 界面

文档界面

image.png

调试工具界面

image.png

需求背景

Swagger 是一个规范和完整的Api文档生成框架。方便开发者生成和调试接口，knife4j 是集成 swagger 的文档框架，可以说是Swagger的加强版，knife4j-ui 相比 swagger-ui 界面更加简洁美观，操作更加便捷。

knife4j-ui 上包含了api 调试工具，虽然操作比较友好，但是其参数都是手工填上去的，遇到一些动态参数，每次手工填写的话会很慢烦。

比如说后台接口需要对参数进行签名校验，如果每次都在自己算好再填上去的话，过程是相当繁琐耗时的。

假设有个接口
http://127.0.0.1/user?id=99&timestmp=1235486&sign=89098475
id：用户Id
timestamp：时间戳
sign：参数签名 = sign(timestamp+id)

因为参数 timestamp 是不断变化的
生成的 sign 也是不断变话的

如果用 knife4j-ui api 调试工具调试接口的话，每次请求都需要先手工计算 sign 然后在把计算出来的 sign 值 填入 knife4j-ui 过程会非常麻烦

此时就需要自定义 knife4j-ui 界面了，把Api 的签名算法集成到 knife4j-ui 上，此时就不需要手工计算并填写参数了。

这只是需要自定义 knife4j-ui 的一个场景，实际上每家公司，或者不同的系统都会有不同的接口规范，这时候如果要使用 swagger 最好自定义 UI 界面。

自定义 knife4j-ui 步骤

第一步，集成 knife4j，并排除自带UI库 knife4j-spring-ui

image.png image.png

通过查看 knife4j-spring-boot-starter 依赖可以发现，knife4j-spring-boot-starter 引入了 swagger 库 以及 knife4j-spring-ui 库，knife4j-spring-ui jar包内包含了所有web页面静态资源，我们需要自定义页面，需要移除 knife4j-spring-ui 并引用自己修改后的 web资源

先排除自带的ui库

    <properties>
        <knife4j.version>2.0.2</knife4j.version>
    </properties>
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>${knife4j.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>com.github.xiaoymin</groupId>
                    <artifactId>knife4j-spring-ui</artifactId>
                </exclusion>
        </exclusions>
    </dependency>

第二步，下载 knife4j-spring-ui 源码修改编译

到 knife4j-spring-ui 项目地址下载源代码，注意 版本号要和上面排除的一致，小编这里吧呢本号是 2.0.2 ，那么就需要下载 tag标签为 2.0.2 的代码

image.png image.png

下载后解压

image.png

使用 编译工具打开项目，推荐使用 Visual Studio Code 打开编辑 knife4j-vue 源代码, 打包静态资源

image.png

打包命令

yarn install
yarn build
最后生成dist文件夹

源码地址上有教如何打包静态资源，这个需要一点前端知识，可以让前端工程师进行修改并打包。如果不懂怎么改可私信我聊

第三部，新增maven webapp 项目，将修改后生成的静态资源文件打包成jar包 xbs-knife4j-ui

image.png image.png

第四步，在原项目引入 xbs-knife4j-ui

<!--        排除自带的 knife4j-spring-ui 库，使用自定义的UI库 xbs-knife4j-ui-->
<!--        自带UI库请参考 document 文件夹 knife4j-ui.md-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>${knife4j.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>com.github.xiaoymin</groupId>
                    <artifactId>knife4j-spring-ui</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        
<!--        引入自定义的UI库 此处以模块的方式引入 ，也可以直接引入生成的jar包-->
        <dependency>
            <groupId>org.xbs</groupId>
            <artifactId>xbs-knife4j-ui</artifactId>
            <version>2.0.2</version>
        </dependency>

第五部，配置项目web资源访问路径

package org.xbs.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.http.HttpMessageConverters;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class AuthSwaggerWebConfig implements WebMvcConfigurer {

    @Autowired
    private HttpMessageConverters httpMessageConverters;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
//        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/knife4j/");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

将项目跑起来，大功告成