在接口平臺的功能優化之路上，我們一直致力于探索如何讓接口提供方能夠更便捷地將接口信息發布到平臺。經過一番深入調研，我們驚喜地發現，公司絕大多數項目都引入了 Swagger，這一發現為我們開啟了新的優化思路 —— 通過解析 Swagger 來實現接口信息的高效收集與發布。起初，我們以為解析工作不過是小菜一碟，上手后才發現，雖然解析本身并不復雜，但對象的組裝過程卻相當繁瑣。不過，幸運的是，我們找到了一款強大的開源組件庫 ——Swagger Parse，它的出現大大縮短了解析工作的時間和難度，讓整個流程變得順暢許多。

探秘 Swagger Parser：接口解析的得力助手

Swagger Parser 是一款專門用于解析和驗證 OpenAPI 規范（涵蓋 2.0 和 3.x 版本）的強大庫。它就像是一位專業的翻譯官，能夠將定義 API 的 JSON 或 YAML 文件 “翻譯” 成易于操作的對象表示，比如在 Java 中常用的 POJO。借助 Swagger Parser，開發者可以輕松讀取、解析并處理 OpenAPI 定義，從而深入理解 API 的結構和行為。這一功能對于自動化工具、代碼生成器以及其他需要處理 API 描述的應用程序而言，堪稱是 “神器”。舉個例子，通過解析 OpenAPI 文檔，我們能夠自動生成客戶端 SDK、服務器存根、文檔頁面等，大大提高開發效率，減少重復性勞動。
具體來說，SwaggerParser 類提供了多種方法，支持從不同的輸入源進行解析，包括 URL、文件路徑、InputStream 等，并且會返回一個代表整個 API 定義的對象模型，方便我們進行進一步的操作，比如遍歷 API 路徑、獲取參數信息、響應模式等。

實戰演練：手把手教你使用 Swagger Parser

1、項目中引入swagger parse GAV

<dependency>
            <groupId>io.swagger.parser.v3</groupId>
            <artifactId>swagger-parser</artifactId>
            <version>2.1.13</version>
        </dependency>

2、解析 OpenAPI 文檔

a、 從文件路徑解析

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.parser.v3.SwaggerParser;

public class SwaggerParseExample {
    public static void main(String[] args) {
        // 從文件路徑解析 OpenAPI 文檔
        OpenAPI openAPI = new SwaggerParser().readLocation("path/to/api-spec.yaml", null, null).getOpenAPI();
        System.out.println(openAPI.getInfo().getTitle());
    }
}

b、 從 URL 解析

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.parser.v3.SwaggerParser;

public class SwaggerParseExample {
    public static void main(String[] args) {
        // 從 URL 解析 OpenAPI 文檔
        OpenAPI openAPI = new SwaggerParser().readLocation("https://api.example.com/v2/api-docs", null, null).getOpenAPI();
        System.out.println(openAPI.getInfo().getTitle());
    }
}

c、 從字符串內容解析

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.parser.v3.SwaggerParser;

public class SwaggerParseExample {
    public static void main(String[] args) {
        String swaggerContent = "openapi: 3.0.0\ninfo:\n  title: Sample API\n  version: 1.0.0";
        
        // 從字符串內容解析 OpenAPI 文檔
        OpenAPI openAPI = new SwaggerParser().parse(swaggerContent);
        System.out.println(openAPI.getInfo().getTitle());
    }
}

3、操作解析后的對象

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.paths.PathItem;
import io.swagger.v3.oas.models.servers.Server;

public class SwaggerParseExample {
    public static void main(String[] args) {
        // 假設已經通過某種方式獲取了 OpenAPI 對象
        OpenAPI openAPI = ...;

        // 獲取 API 的基本信息
        Info info = openAPI.getInfo();
        System.out.println("API Title: " + info.getTitle());
        System.out.println("API Version: " + info.getVersion());

        // 獲取 API 的服務器信息
        for (Server server : openAPI.getServers()) {
            System.out.println("Server URL: " + server.getUrl());
        }

        // 遍歷所有 API 路徑
        for (String path : openAPI.getPaths().keySet()) {
            PathItem pathItem = openAPI.getPaths().get(path);
            System.out.println("Path: " + path);
            if (pathItem.getGet() != null) {
                System.out.println("  GET method available");
            }
            if (pathItem.getPost() != null) {
                System.out.println("  POST method available");
            }
            // 其他 HTTP 方法...
        }
    }
}

更多詳細示例可以查看官網

https://github.com/swagger-api/swagger-parser

總結與福利：完整解析示例大放送

使用 swagger-parse 解析 Swagger 確實能夠讓我們的工作事半功倍，但在實際操作中，仍然會遇到一些繁瑣的細節。為了幫助大家更好地掌握這一技術，文末特別為大家準備了一個完整的解析示例，感興趣的小伙伴可以直接點擊下方鏈接查看：

https://github.com/lyb-geek/springboot-learning/tree/master/springboot-swagger-parse