放弃丑陋的 swagger-ui，使用 knife 接口文档生成神器_knifeui.swagger.net

knife Gitee 地址：https://gitee.com/xiaoym/knife4j

接口生成利器 knife 介绍

之前项目中一直在使用 swagger 生成后台接口文档，很好用，至少比之前用 word 写接口文档 postman 调试接口方便多了。swagger 提供了一套前端页面，但是需要在代码中加入注解，如： @Api @ApiOperation 等，耦合度比较高，但使用起来很方便。对我强迫症的我来说，swagger-ui 页面奇丑无比，给我的感觉就是特别乱，并且没办法保存常用的参数，使用起来很不方便。

这篇文章来介绍 knife，是 swagger 的增强版。该UI增强包主要包括两大核心功能：文档说明 和 在线调试

• 文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，使用 knife 能根据该文档说明，对该接口的使用情况一目了然。
• 在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，而不必通过其他测试工具测试接口是否正确，简介、强大。并且可以实现缓存请求参数，设置header 或 query 全局参数和值。

功能不过多介绍，直接上图演示：

springboot 整合 knife

springboot 基本框架搭建就不过多介绍了，直接演示 springboot 整合 knife 需要改动的配置。

pom.xml 文件增加依赖

由于是 springfox-swagger 的增强UI包,所以基础功能依然依赖 swagger，springfox-swagger 的 jar 包必须引入。然后引入 knife4j-spring-ui 替代原来的 swagger-ui。

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-ui</artifactId>
  <version>3.0.2</version>
</dependency>
1
2
3
4
5
6
7
8
9
10
11

编写Swagger2Config配置文件

Swagger2Config 文件内容如下：

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {

        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("台接口")
                .description("这里描述内容")
                .contact(new Contact("Liuyanmin", "", ""))
                .termsOfServiceUrl("http://localhost:60000/")
                .version("1.0")
                .build();

        return new Docket(DocumentationType.SWAGGER_2)
                .host("http://localhost:60000/")
                .groupName("后台接口")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

访问地址，knife 默认访问地址是：http://${host}:${port}/doc.html

swagger-ui 的样式页面还是可以访问的，地址：http://${host}:${port}/swagger-ui.html，这个不建议使用了，页面太丑了，了解一下就可以了。

注意事项

SpringBoot 中访问 doc.html 或 swagger-ui.html 报404的解决办法

@Configuration
public class IntercpetorConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 设置swagger静态资源访问
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}
1
2
3
4
5
6
7
8
9
10
11

Springfox-swagger 默认提供的接口和依赖的资源文件需要在拦截器或权限验证中过滤掉，过滤内容如下：

/swagger-ui.html,/swagger-resources/**,/csrf,/webjars/**
1

总结

若项目中之前使用过 swagger 生成接口文档，改成 knife 其实很简单，只需要两步：

1. pom.xml 中把 swagger-ui jar包替换成 knife4j-spring-ui
2. 访问地址由原来的 http://${host}:${port}/swagger-ui.html 改成 http://${host}:${port}/doc.html

就这么简单。

还有更多优秀开源的接口文档生成工具，感兴趣的可以自己看一下。

gitbook

smart-doc

redoc

yapi

apidoc

showdoc