gateway聚合swagger3統一管理api文檔

来源:https://www.cnblogs.com/better-farther-world2099/archive/2022/03/31/16081774.html
-Advertisement-
Play Games

springboot微服務整合swagger3方法很簡單,下文會演示。但是在分散式項目中如果每個微服務都需要單獨的分開訪問獲取介面文檔就不方便了,本文將詳細講解springcloud gateway網關如何聚合統一管理swagger介面文檔。 先貼張整合後的效果圖(通過切換左上角的下拉視窗獲取每個微 ...


  springboot微服務整合swagger3方法很簡單,下文會演示。但是在分散式項目中如果每個微服務都需要單獨的分開訪問獲取介面文檔就不方便了,本文將詳細講解springcloud gateway網關如何聚合統一管理swagger介面文檔。

先貼張整合後的效果圖(通過切換左上角的下拉視窗獲取每個微服務的介面文檔):

一、swagger簡介

  • 基於 OpenAPI 規範(OpenAPI Specification,OAS)構建的開源介面文檔自動生成工具,可以讓開發人員快速設計、構建、記錄以及使用 Rest API。
  • 目前的版本有swagger2.0和3.0,swagger2於17年停止維護,現在最新的版本為17年發佈的 Swagger3(Open Api3)。
  • Swagger 主要包含了以下三個部分:
    •   Swagger Editor:基於瀏覽器的編輯器,我們可以使用它編寫我們 OpenAPI 規範。
    •   Swagger UI:它會將我們編寫的 OpenAPI 規範呈現為互動式的 API 文檔,後文我將使用瀏覽器來查看並且操作我們的 Rest API。
    •   Swagger Codegen:它可以通過為 OpenAPI(以前稱為 Swagger)規範定義的任何 API 生成伺服器存根和客戶端 SDK 來簡化構建過程。

  • SpringFox介紹(是 spring 社區維護的一個非官方項目)
    •   是一個開源的API Doc的框架,Marty Pitt編寫了一個基於Spring的組件swagger-springmvc,用於將swagger集成到springmvc中來, 它的前身是swagger-springmvc,可以將我們的Controller中的方法以文檔的形式展現。官方定義為: Automated JSON API documentation for API's built with Spring。

二、Springboot2.x整合Swagger3.x

首先看下單體微服務是如何整合swagger3的,事實上這也是後面gateway網關聚合統一文檔的步驟之一。

步驟一:

SpringBoot添加pom文件依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

如果想讓瀏覽器展示的UI效果更好看一點,需要引入最新的下麵的依賴

<!--swagger UI-->
 <dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-ui</artifactId>
     <version>3.0.3</version>
 </dependency>

步驟二:

配置文件增加配置

swagger:
  enable: true
  application-name: 鑒權配置中心介面
  application-version: 1.0
  application-description: 鑒權配置中心

步驟三:

創建配置類

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;

import io.swagger.annotations.ApiOperation;
import lombok.Data;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author: shf description: date: 2022/3/28 11:35
 */
@Component
@EnableOpenApi
@ConfigurationProperties(prefix = "swagger")
@Data
public class SwaggerConfig {

    /**
     * 是否開啟swagger,生產環境一般關閉,所以這裡定義一個變數
     */
    private Boolean enable;

    /**
     * 項目應用名
     */
    private String applicationName;

    /**
     * 項目版本信息
     */
    private String applicationVersion;

    /**
     * 項目描述信息
     */
    private String applicationDescription;

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .pathMapping("/")

                // 定義是否開啟swagger,false為關閉,可以通過變數控制,線上關閉
                .enable(enable)

                //配置api文檔元信息
                .apiInfo(apiInfo())

                // 選擇哪些介面作為swagger的doc發佈
                .select()

                //apis() 控制哪些介面暴露給swagger,
                // RequestHandlerSelectors.any() 所有都暴露
                // RequestHandlerSelectors.basePackage("net.xdclass.*")  指定包位置
                // withMethodAnnotation(ApiOperation.class)標記有這個註解 ApiOperation
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

                .paths(PathSelectors.any())

                .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(applicationName)
                .description(applicationDescription)
                .contact(new Contact("鑒權中心平臺介面文檔", "www.yifeng.com", "[email protected]"))
                .version(applicationVersion)
                .build();
    }

}

啟動服務看下效果:

瀏覽器訪問http://localhost:9799/doc.html 

埠號是你服務配置指定的

三、gateway統一聚合

成功完成上面微服務整合swagger的步驟後,還需要在網關中增加配置

步驟一:

同樣的引入依賴:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>3.0.3</version>
</dependency>

步驟二:

配置文件:

spring:
  cloud:
    gateway:
      globalcors:
        cors-configurations:
          '[/**]':
            allowCredentials: true
            allowedOrigins: "*"
            allowedMethods: "*"
            allowedHeaders: "*"
      routes:
        - filters:
            - RequestTime=true
            - StripPrefix=1
          id: core-route
          predicates:
            - Path=/core/**
          uri: xxxxxxxx


gateway-config:
  uriWhitelist:
    - /v3/api-docs

在網關的全局過濾器中要將配置的白名單放行。

步驟三:

添加路由枚舉類,將上面配置文件中的每個微服務的路由ID替換為中文,即在UI頁面的左上角顯示的微服務文檔名稱。

/**
 * 服務路由枚舉
 *
 * @author shf
 * @date Created in 2022-03-28 16:28
 */
public enum ServerRouteEnum {

    /**
     * 路由信息
     */
    CORE_ROUTE("core-route", "開放平臺鑒權配置介面");

    private String routeId;
    private String swaggerInfo;

    ServerRouteEnum(String routeId, String swaggerInfo) {
        this.routeId = routeId;
        this.swaggerInfo = swaggerInfo;
    }

    /**
     * 根據路由id獲取swagger信息
     *
     * @param routId 路由id
     * @return swagger信息
     */
    public static String getSwaggerInfoByRoutId(String routId) {
        for (ServerRouteEnum routeEnum : ServerRouteEnum.values()) {
            if (routId.equals(routeEnum.getRouteId())) {
                return routeEnum.getSwaggerInfo();
            }
        }
        return null;
    }

    /**
     * @return the routeId
     */
    public String getRouteId() {
        return routeId;
    }

    /**
     * @param routeId : the routeId to set
     */
    public void setRouteId(String routeId) {
        this.routeId = routeId;
    }

    /**
     * @return the swaggerInfo
     */
    public String getSwaggerInfo() {
        return swaggerInfo;
    }

    /**
     * @param swaggerInfo : the swaggerInfo to set
     */
    public void setSwaggerInfo(String swaggerInfo) {
        this.swaggerInfo = swaggerInfo;
    }
}

最後一步:

新增配置類:

部分說明:

①SwaggerResource:處理的是UI頁面中頂部的選擇框以及拉取到每個微服務上swagger介面文檔的json數據。

②RouteLocator:獲取spring cloud gateway中註冊的路由

import org.apache.commons.lang3.StringUtils;
import org.springframework.cloud.gateway.config.GatewayProperties;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.support.NameUtils;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;

import java.util.ArrayList;
import java.util.List;

import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;

/**
 * @author: shf description: date: 2022/3/28 14:16
 */
@Component
@Primary
public class SwaggerProvider implements SwaggerResourcesProvider {
    public static final String API_URI = "/v3/api-docs";
    private final RouteLocator routeLocator;
    private final GatewayProperties gatewayProperties;

    public SwaggerProvider(RouteLocator routeLocator, GatewayProperties gatewayProperties) {
        this.routeLocator = routeLocator;
        this.gatewayProperties = gatewayProperties;
    }

    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<String> routes = new ArrayList<>();
        // 取出gateway的route
        routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
        // 結合配置的route-路徑(Path),和route過濾,只獲取在枚舉中說明的route節點
        gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId()))
                .forEach(routeDefinition -> routeDefinition.getPredicates().stream()
                        // 目前只處理Path斷言  Header或其他路由需要另行擴展
                        .filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
                        .forEach(predicateDefinition -> {
                                    String routeId = routeDefinition.getId();
                                    String swaggerInfo = ServerRouteEnum.getSwaggerInfoByRoutId(routeId);
                                    if (StringUtils.isNotEmpty(swaggerInfo)) {
                                        resources.add(swaggerResource(swaggerInfo, predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0").replace("/**", API_URI)));
                                    }
                                }
                        ));
        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion("3.0");
        return swaggerResource;
    }

}

 

瀏覽器訪問:

舊版UI:http://localhost:9999/swagger-ui/index.html

新版UI:http://localhost:9999/doc.html

 


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • 博客推行版本更新,成果積累制度,已經寫過的博客還會再次更新,不斷地琢磨,高質量高數量都是要追求的,工匠精神是學習必不可少的精神。因此,大家有何建議歡迎在評論區踴躍發言,你們的支持是我最大的動力,你們敢投,我就敢肝 ...
  • 函數的嵌套有兩種方式: 交叉嵌套 迴環嵌套 交叉嵌套 交叉嵌套的方式是在本函數中調用同一級或上一級函數的嵌套方法: def func(foo): print(1) foo() print(3) def a(): print(1) b = func(a) print(b) 輸出的結果為: 1 1 3 ...
  • redis的基本命令學習 1.簡單理解redis 基於記憶體的key-value資料庫基於c語言編寫的,可以支持多種語言的api //set每秒11萬次,取get 81000次支持數據持久化value可以是string,hash, list, set, sorted set 使用場景: 去最新n個數據 ...
  • 前言 首先描述下業務場景,有一個介面,其中存在耗時操作,耗時操作的執行結果將寫入數據表中,不需要通過該介面直接返回。 因此理論上該介面可以在耗時操作執行結束前返回。本文中使用多線程後臺運行耗時操作,主線程提前返回,實現介面的提前返回。 此外,還嘗試使用協程實現,經驗證,協程適用於多任務併發處理,遇到 ...
  • 簡介 Apollo(阿波羅)是攜程框架部門研發的分散式配置中心,能夠集中化管理應用不同環境、不同集群的配置,配置修改後能夠實時推送到應用端,並且具備規範的許可權、流程治理等特性,適用於微服務配置管理場景。 服務端基於Spring Boot和Spring Cloud開發,打包後可以直接運行,不需要額外安 ...
  • 一、前言 眾所周知,Python 不是一種執行效率較高的語言。此外在任何語言中,迴圈都是一種非常消耗時間的操作。假如任意一種簡單的單步操作耗費的時間為 1 個單位,將此操作重覆執行上萬次,最終耗費的時間也將增長上萬倍。 while 和 for 是 Python 中常用的兩種實現迴圈的關鍵字,它們的運 ...
  • 前言 本片博客記錄快速創建springboot工程的兩種方式。一種是使用maven創建,一種是使用spring initializr創建。開發環境JDK1.8、IDEA、maven。 SpringBoot 優點 可快速構建spring應用 直接嵌入tomcat、jetty、undenrtow伺服器( ...
  • 大家好,我是棧長。 相信大家看到了昨天的 Spring 漏洞,嚴重級別僅為中等,不必慌張, 棧長沒想到的是,自這個月初 Spring Cloud Gateway 突發高危漏洞,現在 Spring Cloud 另外一個 Spring Cloud Function 模塊也淪陷了。。。 來看最新昨天 Sp ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發(一):使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說,近來想嘗試開發一款安卓APP,考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP,畢竟是使用Visual Studio開發工具,使用起來也比較的順手,結合微軟官方的教程進行了安卓 ...
  • 前言 QuestPDF 是一個開源 .NET 庫,用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫,它徹底改變了我們生成 PDF 文檔的方 ...
  • 項目地址 項目後端地址: https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址: ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址: http://tree ...
  • 話不多說,直接開乾 一.下載 1.官方鏈接下載: https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe,運行開始下載SQL server; 二. ...
  • 前言 隨著物聯網(IoT)技術的迅猛發展,MQTT(消息隊列遙測傳輸)協議憑藉其輕量級和高效性,已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫,為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog支持多種接收器用於日誌存儲,增強器用於添加屬性,LogContext管理動態屬性,支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項,適用於不同需求。 ...
  • 目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據,爬取信息時需要模擬瀏覽器行為,否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下: 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • 1.前言 什麼是熱更新 游戲或者軟體更新時,無需重新下載客戶端進行安裝,而是在應用程式啟動的情況下,在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR,Xlua,ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles,Addressable, ...
  • 本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺,其實像阿裡雲,騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後,它會送 ...
  • 通過以下方式可以高效,並保證數據同步的可靠性 1.API設計 使用RESTful設計,確保API端點明確,並使用適當的HTTP方法(如POST用於創建,PUT用於更新)。 設計清晰的請求和響應模型,以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證,確保接收到的數據符合預期格 ...