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

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

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

實戰(zhàn)演練：手把手教你使用 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、 從字符串內(nèi)容解析

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";
        
        // 從字符串內(nèi)容解析 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) {
        // 假設(shè)已經(jīng)通過某種方式獲取了 OpenAPI 對象
        OpenAPI openAPI = ...;

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

        // 獲取 API 的服務(wù)器信息
        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 方法...
        }
    }
}

更多詳細(xì)示例可以查看官網(wǎng)

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

總結(jié)與福利：完整解析示例大放送

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

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