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
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
如果开发者继续使用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
@EnableKnife4j
public 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 = "测试模块")
@RestController
public class DemoController {
@ApiImplicitParam(name = "name", value = "姓名", required = true)
@ApiOperation(value = "入门程序,Hello World")
@PostMapping("/helloWorld")
public ResponseEntity<String> 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;
@Configuration
public 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: 8081
spring:
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.Driver
mybatis:
# 配置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
文档
本处展示测试模块接口的文档:
自测
本处展示测试模块的自测方法