一、快速上手
1、引入依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.2</version>
</dependency>
2、在配置文件中进行配置
# Knife4j配置信息
knife4j:
# Swagger-API文档基础信息配置
api-docs:
groupName: xxx项目API文档
apiBasePackage: 导入项目中需要生成文档的接口基础包名
title: xxx API接口文档
description: xxx接口文档描述信息
contact:
name: xxxx
email: xxxx
url: "xxx"
version: 1.0.0
license:
name: xxxx
url: xxxx
termsOfServiceUrl: xxxx
host: xxxx
# GatewayAPI配置信息
gateway:
globalLatencyTiming: true
3、创建接口文档类
@RestController
@Api(tags = "测试接口管理")
@RequestMapping("/test")
public class TestController {
@ApiOperation(value = "测试API", notes = "测试API")
@ApiResponses({@ApiResponse(code = 200, message = "操作成功", response = String.class)})
@GetMapping(value = "/echo/{string}", produces = MediaType.APPLICATION_JSON_VALUE)
public String echo(@PathVariable String string) {
return "echo:" + string;
}
}
4、启动项目，访问http://localhost:port/doc.html即可查看API文档页面。
二、功能详细介绍
1、基本信息配置
在Knife4j Gateway中，可以通过配置文件进行基本信息的配置，或者通过Java注解进行详细的配置。
@Api(tags = {"用户信息管理"})
@ApiInfo(value = "用户信息管理", description = "用户信息管理API接口文档")
@RestController
@RequestMapping(value = "/user")
public class UserController {
@ApiOperation(value = "根据ID获取用户信息", notes = "获取指定ID的用户信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) {
return userService.getUserById(id);
}
}
2、接口说明
在Knife4j Gateway中，使用@Api注解来标记接口说明信息。
@Api(tags = {"用户信息管理"})
public interface UserService {
@ApiOperation(value = "获取所有用户信息", notes = "获取所有用户信息")
List
listAllUser();
}
3、参数说明
在Knife4j Gateway中，使用@ApiImplicitParam注解来标记参数说明信息。
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) {
return userService.getUserById(id);
}
4、返回值说明
在Knife4j Gateway中，使用@ApiResponse注解来标记返回值说明信息。
@ApiResponses({@ApiResponse(code = 200, message = "操作成功", response = String.class)})
@GetMapping(value = "/hello")
public String sayHello() {
return "Hello World!";
}
5、分组管理
在Knife4j Gateway中，可以通过分组管理来区分不同的API接口，方便API接口的管理和查找。
@Api(tags = {"用户信息管理"})
public interface UserService {
@ApiOperation(value = "获取所有用户信息", notes = "获取所有用户信息")
List
listAllUser();
}
@Api(tags = {"订单信息管理"})
public interface OrderService {
@ApiOperation(value = "获取所有订单信息", notes = "获取所有订单信息")
List
listAllOrder();
}
三、常用扩展
1、集成Swagger-Bootstrap-UI
Swagger-Bootstrap-UI是一款基于Swagger2的API文档UI增强工具，可以帮助API文档页面展示的更加美观和易于使用。通过在Knife4j Gateway中引入Swagger-Bootstrap-UI，可以让API文档页面拥有更加丰富的功能。
引入Swagger-Bootstrap-UI的依赖：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.4</version>
</dependency>
在配置文件中启用Swagger-Bootstrap-UI：
# Swagger-Bootstrap-UI配置信息
swagger:
base-package: 扫描项目中需要生成文档的接口基础包名
contact:
name: 某某公司
title: 项目名称 - API接口文档
description: 项目描述信息
enable: true
version: 1.0.0
termsOfServiceUrl: http://xxxx
authorization:
name: Authorization
description: 在请求头中添加Token信息，格式为"Bearer token"
2、API文档访问控制
在一些敏感的项目中，需要对API文档的访问进行控制，防止未授权的人员访问API文档。Knife4j Gateway提供了访问控制的方式，使用Spring Security进行安全控制。
添加Spring Security的依赖：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
配置Spring Security：
@Configuration
@EnableWebSecurity
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
.authorizeRequests()
.antMatchers("/doc.html", "/webjars/**", "/v2/api-docs", "/swagger-resources/**")
.permitAll()
.anyRequest()
.authenticated()
.and()
.formLogin()
.loginPage("/login.html")
.permitAll()
.and()
.logout()
.permitAll();
}
@Override
public void configure(WebSecurity web) throws Exception {
web.ignoring().antMatchers("/css/**", "/js/**", "/webjars/**");
}
}
3、接口文档自定义UI
在Knife4j Gateway中，默认使用了Bootstrap-Vue作为UI框架，但是开发人员可以根据自己的需求进行UI的自定义，以便更好的满足业务需求。
在resources/templates目录下创建自定义的HTML模板，使用FreeMarker或Thymeleaf等模板引擎来渲染页面，然后在配置文件中进行UI的配置即可。
# UI配置信息
knife4j:
ui:
isDefault: false # 是否使用默认UI
url: /doc.html # 访问API文档的URL
title: 项目名称API接口文档 # 页面标题
logo: /static/images/logo.png # Logo图片地址
tagsSorter: alpha # 标签排序方式：alpha/alphabetical/alphaDesc
operationsSorter: method # 操作排序方式：method/methodDesc/path/pathDesc
disableFilter: false # 是否禁用过滤功能
enableSwaggerBootstrapUi: true # 是否启用Swagger-Bootstrap-UI
apiDocsUrl: /v2/api-docs # 获取API文档信息的URL
footer:
name: xxx公司 # 版权信息
url: http://xxxx # 链接地址
四、常见问题
1、如何在Knife4j Gateway中使用全局异常处理？
Knife4j Gateway默认使用SpringBoot的全局异常处理，但是在一些特殊的业务场景中，可能需要自定义全局异常处理。可以通过@ControllerAdvice注解来实现的全局异常处理。
@ControllerAdvice
public class GlobalExceptionHandler {
/**
* 处理异常：NullPointerException
*
* @param e NullPointerException异常
* @return 错误信息
*/
@ExceptionHandler(value = {NullPointerException.class})
public ResponseEntity
handleNullPointerExceptionException(Exception e) {
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("系统繁忙！");
}
}
2、如何为Knife4j Gateway中的接口设置访问限制？
为了保护系统的安全和稳定，可能需要为Knife4j Gateway中的接口设置访问限制。可以通过使用Spring Security等安全框架来为接口设置访问限制。
3、如何将Knife4j Gateway中的API文档集成到SwaggerHub中？
可以使用SwaggerHub提供的导入功能，将Knife4j Gateway中的API文档导入到SwaggerHub中进行管理。
在SwaggerHub中，选择“APIs”菜单，然后在“New API”下拉菜单中选择“Import API”，在弹出的窗口中选择“Import from Remote URL”，输入Knife4j Gateway中API文档的URL，然后点击“Import API”按钮完成导入。
五、总结
通过本文的介绍，不难看出Knife4j Gateway具有许多丰富的功能和优秀的易用性，对于开发人员来说是一款非常实用和优秀的API文档管理工具。使用Knife4j Gateway可以让开发人员轻松地创建、维护和分享API文档，从而提高项目的效率和可维护性。
