Knife4j实现微服务聚合API文档实战

Knife4j实现微服务聚合API文档实战

SpringBoot集成knife4j

想要构建一个单体是的API文档其实非常简单。只需要构建一个SpringBoot项目，添加knife4j的maven依赖如下：

<!-- swagger -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.20</version>
    <scope>provided</scope>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

SpringBoot的其他配置就省略了，自行查阅。启动项目即可，访问http://localhost/doc.html，如下图

微服务聚合API文档

在微服务环境下，我们每个服务都有各自的API文档，这样访问起来非常麻烦，那么此时我们就需要使用聚合API文档了。knife4j也具备聚合文档的能力，我们需要创建一个独立的SpringBoot聚合服务，然后添加一下maven依赖：

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

微服务聚合模式分为Disk、Cloud、Eureka、Nacos四种模式，我这里先以Cloud模式为例。

配置yml

# knife4j配置
knife4j:
  # 开启聚合
  enableAggregation: true
  # Cloud模式
  cloud:
  	# 开启
    enable: true
    # 路由配置
    routes:
      - name: easypoi测试
        uri: localhost:8001
        location: /v2/api-docs?group=WEB接口文档1.0版本
      - name: kafka测试
        uri: localhost:8002
        location: /v2/api-docs?group=WEB接口文档1.0版本

启动项目如下：

注意的是，这边location必须使用如下图所示的内容，否则无法识别，会报异常

微服务聚合模式

微服务聚合方式分为Disk、Cloud、Eureka、Nacos四种模式，只是配置不同，都很简单

Disk本地模式

开发者只需要在Spring Boot的项目中存在OpenAPI规范的JSON文件即可进行聚合

配置yml配置文件如下：

server:
  port: 9090
knife4j:
  enableAggregation: true
  disk:
    enable: true
    routes:
      - name: 用户
        location: classpath:openapi/user.json

配置目录如下：

启动后效果如下：

Cloud模式聚合

Cloud(云端)模式和Disk模式大同小异，主要的区别是获取OpenAPI规范的方式换成了基于HTTP接口而已

配置yml配置文件如下：

# knife4j配置
knife4j:
  # 开启聚合
  enableAggregation: true
  # Cloud模式
  cloud:
  	# 开启
    enable: true
    # 路由配置
    routes:
      - name: easypoi测试
        uri: localhost:8001
        location: /v2/api-docs?group=WEB接口文档1.0版本
      - name: kafka测试
        uri: localhost:8002
        location: /v2/api-docs?group=WEB接口文档1.0版本

Eureka注册中心聚合

从Eureka注册中心进行聚合的模式和Cloud模式大同小异，主要的区别是通过serviceName来替代了真实的目标服务地

knife4j:
  enableAggregation: true
  eureka:
    enable: true
    serviceUrl: http://localhost:10000/eureka/
    routes:
      - name: easypoi测试
        serviceName: service-easypoi
        location: /v2/api-docs?group=WEB接口文档1.0版本
        servicePath: /easypoi
      - name: kafka测试
        serviceName: service-kafka
        location: /v2/api-docs?group=WEB接口文档1.0版本
        servicePath: /kafka

Nacos注册中心聚合

Nacos的配置和Eureka几乎一模一样，唯一不同的区别是在yml进行配置的时候，使用的是knife4j.nacos开头，其他基本都是一样。

knife4j:
  enableAggregation: true
  nacos:
    enable: true
    serviceUrl: http://localhost:8848/
    routes:
      - name: easypoi测试
        serviceName: service-easypoi
        location: /v2/api-docs?group=WEB接口文档1.0版本
        servicePath: /easypoi
      - name: kafka测试
        serviceName: service-kafka
        location: /v2/api-docs?group=WEB接口文档1.0版本
        servicePath: /kafka