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

以前接口文檔都是直接用絲襪哥的绳慎，最近幾年一直用大佬的這個：Knife4j，尤其是到4.0.0版本以后，已經(jīng)非常好用了杏愤。支持Swagger2規(guī)范和OpenAPI3規(guī)范靡砌，同時也有Spring Boot 2.x和Spring Boot 3.x的區(qū)分，還是很全面的珊楼，尤其Spring Boot 3.x版本通殃，基本不用什么配置，方便厕宗。在微服務(wù)方案中画舌，Knife4j更給出了gateway網(wǎng)關(guān)聚合版本。用起來真的很爽已慢。
先看官方文檔
本次使用版本如下：

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

1. 微服務(wù)模塊

基本就是照搬的官網(wǎng)例子曲聂，不用改什么。除非有特別需要配置的佑惠，我感覺一般這個就夠了朋腋。

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 文檔

該微服務(wù)模塊可以直接看接口文檔的：http://ip:port/doc.html

image.png

2. Gateway網(wǎng)關(guān)模塊

這個配置有手動和自動發(fā)現(xiàn) 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 成為了推薦的負載均衡方案。為了靈活性特愿，需要手動引入仲墨，不然請求到不了各個服務(wù)-->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>
<!-- 做資源服務(wù)器權(quán)限校驗用的，沒用別引入 -->
<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時會自動生成路由規(guī)則洽议，我們手動配置宗收，值設(shè)置false
          enabled: false
          lowerCaseServiceId: true
      routes:
          # 自定義路由 ID
        - id: oauth2-route
          # 采用 LoadBalanceClient 方式請求，以 lb:// 開頭亚兄，后面的是注冊在 Nacos 上的服務(wù)名
          uri: lb://oauth2-server
          # Predicate 斷言混稽，主要作用是匹配用戶的請求路徑，有很多種用法
          predicates:
            # 路徑匹配审胚，一般是指要走網(wǎng)關(guān)時要寫的路徑地址
            - Path=/gateway/oauth2/**
          filters:
            # 指路由到其他服務(wù)時去掉path中幾層路徑匈勋，如值為1，則去掉1層膳叨，即去掉/gateway
            - StripPrefix=1
        - id: resource-route
          uri: lb://resource-server
          predicates:
            - Path=/gateway/resource/**
          filters:
            - StripPrefix=1
knife4j:
  gateway:
    # 是否開啟
    enabled: true
    # 排序規(guī)則(tag/operation排序自4.2.0版本新增)
    # 取值：alpha-默認排序規(guī)則洽洁，官方swagger-ui默認實現(xiàn),order-Knife4j提供的增強排序規(guī)則，開發(fā)者可擴展x-order菲嘴，根據(jù)數(shù)值來自定義排序
    tags-sorter: order
    operations-sorter: order
    # 指定服務(wù)發(fā)現(xiàn)的模式聚合微服務(wù)文檔饿自，并且是默認`default`分組
    # 這是手動模式的汰翠，需要指定url，注意 url 和 context-path 這2個值的填寫
#    strategy: manual
#    routes:
#      - name: 認證服務(wù)
#        # 真實通過網(wǎng)關(guān)訪問子服務(wù)接口文檔的uri地址：
#        # /v3/api-docs?group=default是固定值昭雌，
#        # /oauth2 是微服務(wù)的 context-path
#        # /gateway 是我在網(wǎng)關(guān)路由斷言中自定義添加的复唤，可以是/api等其他的，如果沒有烛卧，這一層可以不用
#        url: /gateway/oauth2/v3/api-docs?group=default
#        service-name: oauth2-server
#        # 路由前綴
#        # 這個值在V3版本中佛纫，界面中調(diào)試時添加到微服務(wù)中uri前面的，一般和上面url前面部分相同
#        context-path: /gateway/oauth2
#        order: 1
    # 自動發(fā)現(xiàn)模式总放，讀取nacos注冊中心里的微服務(wù)
    strategy: discover
    discover:
      enabled: true
      # 指定版本號(Swagger2|OpenAPI3)
      version : openapi3
      # 需要排除的微服務(wù)(eg:網(wǎng)關(guān)服務(wù))
      excluded-services:
        - gateway-server
      # 各個聚合服務(wù)的個性化配置呈宇，key:注冊中心中的服務(wù)名稱，value：個性化配置
      service-config:
        oauth2-server:
          # 排序
          order: 1
          # 前端顯示名稱
          group-name : 認證服務(wù)
          # 重新指定basePath局雄，一般在OpenAPI3規(guī)范中需要
          context-path: /
        resource-server:
          # 排序
          order: 2
          # 前端顯示名稱
          group-name : 資源服務(wù)
          # 重新指定basePath甥啄，一般在OpenAPI3規(guī)范中需要
          context-path: /

2.3 網(wǎng)關(guān)接口文檔