SpringBoot swagger2 knife4j 自定义UI

标签：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×tmp=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库

    
        2.0.2
    
    
        com.github.xiaoymin
            knife4j-spring-boot-starter
            ${knife4j.version}
            
                
                    com.github.xiaoymin
                    knife4j-spring-ui
                
        
    

第二步，下载 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

        
            com.github.xiaoymin
            knife4j-spring-boot-starter
            ${knife4j.version}
            
                
                    com.github.xiaoymin
                    knife4j-spring-ui
                
            
        
        

        
            org.xbs
            xbs-knife4j-ui
            2.0.2
        

第五部，配置项目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/");
    }
}

将项目跑起来，大功告成