这是我参与11月更文挑战的第17天，活动详情查看：11月更文挑战
在目前微服务项目中, 通常使用swagger作为在线文档交流使用,但各个微服务的文档都各自管理, 比较分散, 且没有导出离线文档等功能,而knife4j工具可以解决上述问题
1 knife4j工具的介绍
knife4j是2017年开源的一款增强swagger的工具, 主要是为Java开发框架集成Swagger生成Api文档的增强解决方案(主要是Java的Spring MVC, Spring Boot, Spring Cloud等非Java语言)，前身是swagger-bootstrap-ui,取名knife4j是作者希望她能像一把匕首一样小巧,轻量,并且功能强悍.
简单案例
knife4j是增强swagger的工具,所以使用方式,配置等和使用swagger类似.
前提: 准备一个可运行的SpringBoot环境.
1 导入Knife4j依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.7</version>
</dependency>
复制代码2 添加配置文件
@Configuration
@EnableSwagger2WebMvc
public class Knife4jDocConfiguration {
/**
* 构建Docket对象
*/
@Bean
@ConditionalOnMissingBean
public Docket apiDocket2() {
// 默认组名, 文档更具组名查询,不同组名不能聚合
String groupName = "default";
return new Docket(DocumentationType.SWAGGER_2)
// 文档信息
.apiInfo(getApiInfo())
// 组名
.groupName(groupName)
.select()
// 指定Controller扫描包路径(如下面第一个apis方法) 因Controller类上要添加Api注解, 所以可通过指定类上注解
// .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build()
}
/**
* 创建api文档信息
*/
private ApiInfo getApiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
// 设置标题
.title(appName + "服务接口文档")
// 描述
.description("接口的相关文档")
// 作者信息
.contact(new Contact("李白", "www.libai.com", "[email protected]"))
// 版本
.version("1.0")
.build();
}
}
复制代码3 添加控制器
@RestController
@Slf4j
@Api(value = "AConController", tags = "消费者控制器")
public class AConController {
@Autowired
private ProviderFeign providerFeign;
@GetMapping("/consumer")
public String list() {
String info = "我是consumerA,8081 ";
log.info(info);
String result = providerFeign.list();
return JSON.toJSONString(info + result);
}
}
复制代码4 查看文档
访问文档地址http://localhost:8080/doc.html
2 knife4j工具的使用
聚合微服务文档案列
准备服务: 一个文档服务,两个业务服务,nacos注册配置中心
文档服务
1 准备一个可运行的SpringBoot服务
2 添加knife4j依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
复制代码3 application.yml文件添加配置
knife4j:
# 开启聚合
enableAggregation: true
nacos:
enable: true
serviceUrl: http://localhost:8848/nacos
routeAuth:
enable: true
password: nacos
username: nacos
routes:
- name: provider-a服务
serviceName: provider-a
location: /v2/api-docs?group=default
servicePath: /
- name: consumer-a服务
serviceName: consumer-a
location: /v2/api-docs?group=default
servicePath: /
复制代码业务服务1
1 准备一个可运行的SpringBoot服务
2 添加配置类
@Configuration
@EnableSwagger2WebMvc
public class Knife4jDocConfiguration {
/**
* 服务名称
*/
@Value("${spring.application.name:应用}")
private String appName;
/**
* 引入Knife4j提供的扩展类 OpenApiExtensionResolver辅助类需要配置knife4j.enable=true才能自动@Autowired
*/
@Autowired(required = false)
private OpenApiExtensionResolver openApiExtensionResolver;
/**
* 1、限制哪些类可以生成api文档 2、限制哪些url可以生成api文档
*/
@Bean
@ConditionalOnMissingBean
public Docket apiDocket2() {
// 默认组名, 文档更具组名查询,不同组名不能聚合
String groupName = "default";
return new Docket(DocumentationType.SWAGGER_2)
// 文档信息
.apiInfo(getApiInfo())
// 组名
.groupName(groupName)
.select()
// 指定Controller扫描包路径(如下面第一个apis方法) 因Controller类上要添加Api注解, 所以可通过指定类上注解
// .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build()
// 赋予插件体系
.extensions(getExtensions(groupName));
}
/**
* 创建api文档信息
*/
private ApiInfo getApiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
// 设置标题
.title(appName + "服务接口文档")
// 描述
.description("接口的相关文档")
// 作者信息
.contact(new Contact("李白", "www.libai.com", "[email protected]"))
// 版本
.version("1.0")
.build();
}
/**
* 根据组名添加插件
*/
private List<VendorExtension> getExtensions(String groupName) {
return null != openApiExtensionResolver ? openApiExtensionResolver
.buildExtensions(groupName) : new ArrayList<>();
}
}
复制代码3 可在后台配置,添加到自动装配 (增强特性时使用)
在resources文件夹下增加META-INF文件夹,spring.factories文件
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.cf.config.Knife4jDocConfiguration
复制代码ps: 如果有多个自动配置注入使用,\分隔
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.cf.config.Knife4jDocConfiguration,\
com.cf.config.Configuration
复制代码4 添加控制器
@RestController
@Slf4j
@Api(value = "AConController", tags = "消费者控制器")
public class AConController {
@Autowired
private ProviderFeign providerFeign;
@GetMapping("/consumer")
public String list() {
String info = "我是consumerA,8081 ";
log.info(info);
String result = providerFeign.list();
return JSON.toJSONString(info + result);
}
}
复制代码业务服务2
基本配置和服务一相同.
查看文档
1 启动本地nacos ,再依次启动文档服务knife4j-doc服务 , provider-a服务 , consumer-a服务
2 启动本地nacos服务,查看服务列表,发现存在三个服务
knife4j-doc服务
provider-a服务
consumer-a服务
复制代码3 查看文档服务knife4j-doc的文档
http://localhost:8000/doc.html
发现provider-a和consumer-a服务的Controller文档已经被聚合出来,可以查看和测试了.
参考资料: