十五、 Spring Cloud Alibaba 整合Knife4j做接口文档

以前接口文档都是直接用丝袜哥的，最近几年一直用大佬的这个：Knife4j，尤其是到4.0.0版本以后，已经非常好用了。支持Swagger2规范和OpenAPI3规范，同时也有Spring Boot 2.x和Spring Boot 3.x的区分，还是很全面的，尤其Spring Boot 3.x版本，基本不用什么配置，方便。在微服务方案中，Knife4j更给出了gateway网关聚合版本。用起来真的很爽。
先看官方文档
本次使用版本如下：

Spring Cloud Alibaba：2023.0.1.2
Spring Boot：3.3.3
Knife4j：4.4.0
Jdk：17

1. 微服务模块

基本就是照搬的官网例子，不用改什么。除非有特别需要配置的，我感觉一般这个就够了。

1.1 pom.xml

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Knife4j -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
</dependency>
<!-- nacos包 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

1.2 application.yml

spring:
  application:
    name: oauth2-server
# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.example.test.oauth2.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

1.3 文档

该微服务模块可以直接看接口文档的：http://ip:port/doc.html

image.png

2. Gateway网关模块

这个配置有手动和自动发现 2种模式。看哪种适合需要

2.1 pom.xml

<dependency>
   <groupId>org.springframework.cloud</groupId>
   <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<!-- Knife4j-gateway -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-gateway-spring-boot-starter</artifactId>
</dependency>
<!-- nacos包 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
<!-- Spring Cloud Gateway 的早期版本中，Ribbon 被用作默认的负载均衡器, Spring Cloud 2020.0.0 版本开始，Ribbon 被废弃，Spring Cloud LoadBalancer 成为了推荐的负载均衡方案。为了灵活性，需要手动引入，不然请求到不了各个服务-->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>
<!-- 做资源服务器权限校验用的，没用别引入 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

2.2 application.yml

spring: 
  application: 
    name: gateway-server
  cloud: 
    gateway:
      discovery:
        locator:
          # 为true时会自动生成路由规则，我们手动配置，值设置false
          enabled: false
          lowerCaseServiceId: true
      routes:
          # 自定义路由 ID
        - id: oauth2-route
          # 采用 LoadBalanceClient 方式请求，以 lb:// 开头，后面的是注册在 Nacos 上的服务名
          uri: lb://oauth2-server
          # Predicate 断言，主要作用是匹配用户的请求路径，有很多种用法
          predicates:
            # 路径匹配，一般是指要走网关时要写的路径地址
            - Path=/gateway/oauth2/**
          filters:
            # 指路由到其他服务时去掉path中几层路径，如值为1，则去掉1层，即去掉/gateway
            - StripPrefix=1
        - id: resource-route
          uri: lb://resource-server
          predicates:
            - Path=/gateway/resource/**
          filters:
            - StripPrefix=1
knife4j:
  gateway:
    # 是否开启
    enabled: true
    # 排序规则(tag/operation排序自4.2.0版本新增)
    # 取值：alpha-默认排序规则，官方swagger-ui默认实现,order-Knife4j提供的增强排序规则，开发者可扩展x-order，根据数值来自定义排序
    tags-sorter: order
    operations-sorter: order
    # 指定服务发现的模式聚合微服务文档，并且是默认`default`分组
    # 这是手动模式的，需要指定url，注意 url 和 context-path 这2个值的填写
#    strategy: manual
#    routes:
#      - name: 认证服务
#        # 真实通过网关访问子服务接口文档的uri地址：
#        # /v3/api-docs?group=default是固定值，
#        # /oauth2 是微服务的 context-path
#        # /gateway 是我在网关路由断言中自定义添加的，可以是/api等其他的，如果没有，这一层可以不用
#        url: /gateway/oauth2/v3/api-docs?group=default
#        service-name: oauth2-server
#        # 路由前缀
#        # 这个值在V3版本中，界面中调试时添加到微服务中uri前面的，一般和上面url前面部分相同
#        context-path: /gateway/oauth2
#        order: 1
    # 自动发现模式，读取nacos注册中心里的微服务
    strategy: discover
    discover:
      enabled: true
      # 指定版本号(Swagger2|OpenAPI3)
      version : openapi3
      # 需要排除的微服务(eg:网关服务)
      excluded-services:
        - gateway-server
      # 各个聚合服务的个性化配置，key:注册中心中的服务名称，value：个性化配置
      service-config:
        oauth2-server:
          # 排序
          order: 1
          # 前端显示名称
          group-name : 认证服务
          # 重新指定basePath，一般在OpenAPI3规范中需要
          context-path: /
        resource-server:
          # 排序
          order: 2
          # 前端显示名称
          group-name : 资源服务
          # 重新指定basePath，一般在OpenAPI3规范中需要
          context-path: /

2.3 网关接口文档