knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案
Eureka模式原理是，在聚合文档工程配置Eureka注册中心地址和每个服务名称，这样聚合文档工程启动的时候可以从Eureka访问到每个微服务的http接口文档资源地址，从而聚合每个微服务的接口文档
由于聚合文档工程需要能访问到Eureka获取每个微服务的信息才能做聚合，所以在聚合文档工程启动之前要先启动Eureka和需要被聚合的每个微服务，并且每个微服务要成功注册到Eureka中
每个微服务自己要做好Swagger文档的相关配置
版本说明
目前Knife4j的主版本依然是沿用2.x的版本号，也就是从2.0.6版本开始逐步升级，迭代发布时版本会随之升级，但同时3.x版本也会同步更新发布，主要是满足开发者对于springfox3以及OpenAPI3规范的使用
2.x与3.x的版本主要变化是底层springfox所引用的版本不同，但Knife4j提供的Ui其实是同一个，同时兼容OpenAPI2以及OpenAPI3规范，源码请参考knife4j-vue (opens new window)，如果开发者依然想沿用以前Knife4j一直以来发布的2.x版本，请继续更随Knife4j的更新步伐使用2.x的版本即可，如果开发者想尝鲜，则可以考虑3.x的版本
3.x的版本依赖springfox3.0.0，springfox3.0目前也只更新发布了一个版本，从功能稳定性来说，可能不如2.x系列，所以开发者慎重使用，当然,如果是Ui上的一些功能性问题或者Bug，也欢迎开发者向Knife4j发起ISSUE (opens new window)，等springfox3版本趋于稳定后，knife4j的2.x版本就不会在更新，会并向3.x
官网地址官网
依赖
knife4j-spring-boot-starter是knife4j基础依赖，在业务模块引入即可（例如订单服务，支付服务，详细请往下阅读）
knife4j-aggregation-spring-boot-starter是knife4j聚合依赖，在文档模块引入即可（详细请往下阅读）
如果觉得单独引入麻烦，可以在父POM引入
工程 工程目录（此处引入官网图片） 工程说明com.github.xiaoymin knife4j-spring-boot-starter 2.0.9 com.github.xiaoymin knife4j-aggregation-spring-boot-starter 2.0.9
| 工程名字 | 说明 |
|---|---|
| service-server（eureka或者nacos） | Eureka注册中心 |
| service-payment（业务模块） | 一个非常简单的支付服务，包含支付接口 |
| service-order（业务模块） | 一个非常简单的订单服务，包含订单接口 |
| service-doc（文档模块） | 聚合文档工程，也是一个Spring Boot工程，不过需要注意的是基于web的，而非webflux |
在service-payment和service-order等业务模块引入knife4j-spring-boot-starter
在service-doc文档模块引入knife4j-aggregation-spring-boot-starter
服务配置service-payment,service-order等业务模块创建各自的配置文件（不创建的话可能会缺失一些文档基础信息，但是不影响使用）
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
@Bean
public Docket webApiConfig(){
return new Docket(documentationType.SWAGGER_2)
// 创建接口文档的具体信息
.apiInfo(webApiInfo())
// 创建选择器，控制哪些接口被加入文档
.select()
// 指定@ApiOperation标注的接口被加入文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();
}
private ApiInfo webApiInfo(){
return new ApiInfoBuilder()
// 文档标题
.title("elon-cloud接口文档")
// 文档简介
.description("本文档描述了elon-cloud系统的接口定义")
// 版本
.version("1.0")
// 联系人信息
.contact(new Contact("elon", "https://eloncloud.com", "1757xxx385@qq.com"))
// 版权
.license("elon")
.build();
}
service-doc 配置yml文件
server:
port: 10909
knife4j:
enableAggregation: true
eureka:
enable: true
serviceUrl: http://elon-eureka-7001:7001/eureka/ # 注册中心地址
routes:
- name: 支付服务
serviceName: elon-payment-biz # 业务模块服务名称
location: /v2/api-docs?group=default
servicePath: /payment
- name: 订单服务
serviceName: elon-order-biz # 业务模块服务名称
location: /v2/api-docs?group=default
servicePath: /order
其余详细说明请见最下方参数说明
启动按顺序启动service-server，service-payment，service-order，service-doc
即 先启动注册中心，在启动业务模块，最后启动knife4j文档模块
聚合效果 NacosNacos的配置和Eureka几乎一模一样，唯一不同的区别是在yml进行配置的时候，使用的是knife4j.nacos开头，其他基本都是一样
聚合文档doc模块yml详细配置
knife4j.eureka.enable:将该属性设置为true，则代表启用Eureka模式knife4j.eureka.serviceUrl:Eureka注册中心的地址knife4j.eureka.serviceAuth:该属性是一个公共Basic验证属性(可选)，如果Eureka的注册和获取服务需要进行Basic认证，开发者需要配置该属性knife4j.eureka.serviceAuth.enable:是否启用Eureka注册中心Basic验证knife4j.eureka.serviceAuth.usernae:Eureka注册中心Basic用户名knife4j.eureka.serviceAuth.password:Eureka注册中心Basic密码knife4j.eureka.routeAuth:该属性是一个公共Basic验证属性(可选)，如果开发者提供的OpenAPI规范的服务需要以Basic验证进行鉴权访问，那么可以配置该属性，如果配置该属性，则该模式下所有配置的Routes节点接口都会以Basic验证信息访问接口knife4j.eureka.routeAuth.enable:是否启用Basic验证knife4j.eureka.routeAuth.usernae:Basic用户名knife4j.eureka.routeAuth.password:Basic密码knife4j.eureka.routes:需要聚合的服务集合(必选)，可以配置多个knife4j.eureka.routes.name:服务名称(显示名称，最终在Ui的左上角下拉框进行显示)，如果该属性不配置，最终Ui会显示serviceNameknife4j.eureka.routes.serviceName:Eureka注册中心的服务名称knife4j.eureka.routes.uri:该服务的接口URI资源，如果是HTTPS，则需要完整配置knife4j.eureka.routes.location::具体资源接口地址，最终Knife4j是通过注册服务uri+location的组合路径进行访问knife4j.eureka.routes.swaggerVersion:版本号，默认是2.0，可选配置knife4j.eureka.routes.servicePath:该属性是最终在Ui中展示的接口前缀属性，提供该属性的目的也是因为通常开发者在以Gateway等方式聚合时，需要一个前缀路径来进行转发，而最终这个前缀路径会在每个接口中进行追加knife4j.eureka.routes.routeAuth:如果该Route节点的接口开启了Basic，并且和公共配置的Basic不一样，需要单独配置knife4j.eureka.routes.routeAuth.enable:是否启用Basic验证knife4j.eureka.routes.routeAuth.usernae:Basic用户名knife4j.eureka.routes.routeAuth.password:Basic密码
