Excerpt

简介说明 knife是一个很好用的接口文档工具。之前用过swagger，觉得页面不太好，浏览技术网站时，偶然发现swagger-bootstrap-ui，能方便地将接口进行归类。 早期，swagger-boostrap-ui是1.x版本，如今swagger-bootsrap-ui到2.x，同时也更改名字knife4j，适用于单体和微服务项目。 knife4j跟swagger用法基本一样...

简介

说明

本文用示例介绍knife4j的用法。（SpringBoot整合knife4j）

Knife4j是一个很好用的接口文档工具。之前用过Swagger，觉得页面不太好，浏览技术网站时，偶然发现swagger-bootstrap-ui，它能将接口进行归类。

早期，swagger-boostrap-ui是1.x版本，如今swagger-bootsrap-ui到2.x，同时也更改名字Knife4j，适用于单体和微服务项目。

Knife4j跟Swagger用法基本一样

官网

首页：knife4j
文档：knife4j
gitee地址：https://gitee.com/xiaoym/knife4j

实例

官网文档：1.6 快速开始 | knife4j

依赖及配置

依赖

使用OpenAPI3的结构，底层框架依赖springfox3.0.0

    com.github.xiaoymin    knife4j-spring-boot-starter    3.0.3

如果开发者继续使用OpenAPI2的规范结构，底层框架依赖springfox2.10.5版本，那么可以考虑Knife4j的2.x版本

版本的区别如下：

版本说明1.9.6蓝色皮肤风格,开始更名，增加更多后端模块2.0~2.0.5Ui重写，底层依赖的springfox框架版本是2.9.22.0.6~底层springfox框架版本升级至2.10.5，OpenAPI规范是v23.0~底层依赖springfox框架版本升级至3.0.3，OpenAPI规范是v3

Knife4j配置（非必要）

配置方案：使用swagger2**

默认引入包就可以直接用了（无需配置）。本处只是示例如果自定义一些东西该怎么写。

package com.fish.minio.config;import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;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.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration@EnableSwagger2@EnableKnife4jpublic class Knife4jConfiguration {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .useDefaultResponseMessages(false)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("com.fish.minio.controller"))                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .description("Kinfe4j 集成测试文档")                .contact(new Contact("fish", "https://www.toutiao.com/c/user/token/MS4wLjABAAAApJyWoDllDsOZojggLObCblRRqKmUzto4_jHLfM5Da7A/?source=tuwen_detail&log_from=f4b96b06c9fe_1659793089934", "fish@qq.com"))                .version("v1.1.0")                .title("API测试文档")                .build();    }}

代码

Controller

package com.fish.minio.controller;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiOperation;import org.springframework.http.ResponseEntity;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RequestParam;import org.springframework.web.bind.annotation.RestController;@Api(tags = "测试模块")@RestControllerpublic class DemoController {    @ApiImplicitParam(name = "name", value = "姓名", required = true)    @ApiOperation(value = "入门程序，Hello World")    @PostMapping("/helloWorld")    public ResponseEntity helloWorld(@RequestParam(value = "name") String name) {        return ResponseEntity.ok("Hello World，" + name);    }}

新建一个配置类 WebMvcConfigurer 继承 WebMvcConfigurationSupport 类，将 dom.html 过滤掉

package com.fish.minio.config;import org.springframework.context.annotation.Configuration;import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;@Configurationpublic class WebMvcConfigurer extends WebMvcConfigurationSupport {    @Override    public void addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");        super.addResourceHandlers(registry);    }}

application.yml

spring:  profiles:    active: dev

application-dev.yml

server:  port: 8081spring:  datasource:    username: root    password: root.    url: jdbc:mysql://192.168.1.1:3306/test_db?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8    driver-class-name: com.mysql.cj.jdbc.Drivermybatis:  # 配置mapper的扫描，找到所有的mapper.xml映射文件  # 搜索指定包别名  typeAliasesPackage: com.fish.**.mapper  mapperLocations: classpath*:mapper/*Mapper.xml

代码层级结构

测试

访问地址：

http://localhost:8081/doc.html

分组Url

“分组Url”是文档地址，其他软件（比如apifox）可以将它作为导入文档的url。

此网址可以直接访问：http://localhost:8081/v3/api-docs

文档

本处展示测试模块接口的文档：

自测

本处展示测试模块的自测方法