Knife4j聚合Eureka&Nacos

Elon的随笔

已于 2022-03-20 14:50:06 修改

阅读量1.7k

点赞数

文章标签： java

于 2022-03-20 14:49:46 首次发布

本文链接：https://blog.csdn.net/qq_44536533/article/details/123612967

版权

简介

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引入

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

工程

工程目录（此处引入官网图片）

工程说明

工程名字	说明
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 {
    /**
     * 创建Docket存入容器，Docket代表一个接口文档
     * @return
     */
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                // 创建接口文档的具体信息
                .apiInfo(webApiInfo())
                // 创建选择器，控制哪些接口被加入文档
                .select()
                // 指定@ApiOperation标注的接口被加入文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }

    /**
     * 创建接口文档的具体信息，会显示在接口文档页面中
     * @return
     */
    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文档模块

聚合效果

在这里插入图片描述

Nacos

Nacos的配置和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会显示serviceName
knife4j.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密码