源寶導讀：隨著企業信息化進程的逐步深入，互聯網技術的發展和分布式系統應用的日益廣泛，直接導致大量異構系統的存在，這些系統往往各自獨立、封閉運行，相互之間不存在或很少存在數據的交互，由于這種應用分割，多個系統之間往往存在數據的冗余以及功能的重疊，各個系統之間信息傳輸、資源利用困難，形成所謂的“信息孤島”。天際·集成開放平臺，提供輕量化的API、事件、消息、數據集成能力，可以幫助您積木式、配置化的構建高可靠、高性能、低延遲的應用集成解決方案，實現企業云上云下、不同廠商、不同架構、不同協議的應用互聯互通，并且平臺還提供可視化的運維管理、實時的運行監控，保障集成可持續健康運行。當前文章主要闡述集成平臺連接中心的API管理能力，把不同協議、不同廠商的服務轉化成統一標準的Http協議服務，對外提供操作能力。對Http協議的描述，采用國際標準OAS 3.0規范。

一、OAS 3.0 初識

介紹

OAS 3.0即：OpenAPI Specification 3.0.*；OpenAPI 規范 為 REST API 定義了一種標準的、與編程語言無關的接口描述，它允許人類和計算機發現和理解服務的功能，而無需訪問源代碼、附加文檔或檢查網絡流量. 當通過 OpenAPI 正確定義時，消費者可以使用最少的實現邏輯理解遠程服務并與之交互。與接口描述為低級編程所做的類似，OpenAPI 規范消除了調用服務時的猜測。

發展史（來源wiki:https://en.wikipedia.org/wiki/OpenAPI_Specification）

Swagger開發始于 2010 年初，由在在線詞典公司Wordnik工作的 Tony Tam 開始。[3] 2015 年 3 月，SmartBear Software從 Wordnik 的母公司 Reverb Technologies 那里收購了開源 Swagger API 規范。[4]

2015 年 11 月，SmartBear 宣布將在Linux 基金會的贊助下創建一個名為 OpenAPI Initiative 的新組織。其他創始成員公司包括3scale、Apigee、CapitalOne、谷歌、IBM、Intuit、微軟、PayPal和 Restlet。[5]?[6]?[7] SmartBear 向新組捐贈了 Swagger 規范。該小組也在考慮RAML和API Blueprint。[8]?[9]

2016 年 1 月 1 日，Swagger 規范更名為 OpenAPI 規范 (OAS)，并移至新的GitHub 存儲庫。[10]

2016 年 9 月，API World 大會向 SmartBear 頒發了 API 基礎設施獎，以表彰其在 Swagger 上的持續工作。[11]

2017 年 7 月，OpenAPI Initiative 發布了其規范的 3.0.0 版。[12] MuleSoft是替代RESTful API 建模語言(RAML)的主要貢獻者，加入了 OAS 并開源了他們的 API 建?？蚣芄ぞ?#xff0c;該工具可以從 RAML 輸入生成 OAS 文檔。

變更版本

2.0 & 3.0 根節點屬性示意圖

參考：https://swagger.io/blog/news/whats-new-in-openapi-3-0

節點說明?（參考：https://github.com/fishead/OpenAPI-Specification/blob/master/versions/3.0.0.zhCN.md#oasDocument）

OpenAPI 根對象

# OpenAPI 規范版本號 openapi: 3.0.0# API 元數據信息 info:# 服務器連接信息 servers:# API 的分組標簽 tags: # 對所提供的 API 有效的路徑和操作 paths:# 一個包含多種綱要的元素，可重復使用組件 components:# 聲明 API 使用的安全機制 security:# 附加文檔 externalDocs:?

Info 對象

# API 元數據信息 info:title: xx開放平臺接口文檔 # 應用的名稱description: | 簡短的描述信息，支持 markdown 語法。| 表示換行，< 表示忽略換行。version: "1.0.0" # API 文檔的版本信息termsOfService: 'http://swagger.io/terms/' # 指向服務條款的 URL 地址contact: # 所開放的 API 的聯系人信息name: API Support # 人或組織的名稱url: http://www.example.com/support # 指向聯系人信息的 URL 地址email: apiteam@swagger.io # 人或組織的 email 地址license: # 所開放的 API 的證書信息。name: Apache 2.0url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

參考：https://github.com/fishead/OpenAPI-Specification/blob/master/versions/3.0.0.zhCN.md#infoObject

Server 對象

所有的 API 端點都是相對于基本 URL 的。例如，假設 https://api.example.com/v1 的基本 URL 中，/users 端點指的是 https://api.example.com/v1/users。

https://api.example.com/v1/users?role=admin&status=active \ __________________ / \__/ \ ______________________ /服務器URL 端點路徑 查詢參數

Server 表示一個服務器的對象。這里通常填寫測試服務器或者生產服務器的 IP 地址、端口版本號等信息（指定基本 URL）。

# 服務器連接信息 servers:- url: https://development.gigantic-server.com/v1description: 開發服務器- url: https://staging.gigantic-server.com/v1description: 測試服務器- url: https://api.gigantic-server.com/v1description: 生產服務器

參考：https://github.com/fishead/OpenAPI-Specification/blob/master/versions/3.0.0.zhCN.md#serverObject

Tag 對象

Tag 對象用于對 path 對象中的 API 進行分組，可以更美觀的生成文檔。

# API 的分組標簽 tags: - name: petdescription: 與寵物相關的接口externalDocs:description: 外部文檔url: 'http://swagger.io'- name: storedescription: 寵物商店- name: userdescription: 用戶操作相關externalDocs:description: 外部文檔url: 'http://swagger.io'

參考：https://github.com/fishead/OpenAPI-Specification/blob/master/versions/3.0.0.zhCN.md#tagObject

Path 對象

定義各個的端點和操作的相對路徑。這里指定的路徑會和 Server 對象?內指定的URL地址組成完整的URL地址，路徑可以為空，這依賴于 ACL constraints 的設置。

參考：https://github.com/fishead/OpenAPI-Specification/blob/master/versions/3.0.0.zhCN.md#pathsObject

External Documentation 對象

允許引用外部資源來擴展文檔

# 附加文檔 externalDocs:description: Find out more about Swaggerurl: 'http://swagger.io'

參考：https://github.com/fishead/OpenAPI-Specification/blob/master/versions/3.0.0.zhCN.md#externalDocumentationObject

Components 對象

包含開放API規范固定的各種可重用組件。當沒有被其他對象引用時，在這里定義定義的組件不會產生任何效果

# 一個包含多種綱要的元素，可重復使用組件 components:schemas:responses:parameters:examples:requestBodies:headers:securitySchemes:links:callbacks:參考：componentsObject

詳細節點說明參考：https://github.com/fishead/OpenAPI-Specification/blob/master/versions/3.0.0.zhCN.md#oasDocument

基于OAS 規范制作文檔?

在開發團隊中會產生很多基于Http協議的服務， 這些服務需要在團隊中給測試或者接入方或者對外部表達這些服務接口，往往需要產生一個可以被查看的，或需要可以被調試的界面，這種Http具備要素是既定的，國際上多家大型企業參與并制定OAS的規范，對Http協議的各種屬性進行規范表達。更多大家熟知的是不同語言提供的Swagger集成組件，在項目中集成Swagger擴展組件，Swagger會結合語言的一些規范，產生json文檔，以及提供可被閱讀以及調試的可視化界面，直接使用，非常便利，這樣閱讀對象就可以很好的閱讀并調試對應Http服務的各種接口，市面上Swagger組件即為基于OpenApi規范產生的文檔，繼而提供基于文檔規范的可視化界面，在項目中使用Swagger組件上面就可以看到對應的json文檔地址，以及接口的描述

實用過程中，服務如何基于OpenAPI規范產生文檔以及可視化界面

具體項目實現可參考：

• net core:?https://github.com/domaindrivendev/Swashbuckle.AspNetCore

• java :https://github.com/swagger-api/swagger-core

• php:https://github.com/zircote/swagger-php

項目集成組件之后呈現示例：

二：連接器基于OpenApi的管理能力

服務需要對外表達和描述一個接口，集成平臺涉及接口管理的也需要進行表達和描述，其中接口中心和連接中心對接口的表達以及文檔的存儲都為基于OpenApi規范的json文檔，下面描述連接中心模塊，如下

示例圖：

連接器分兩種類型：Http類型連接器，托管連接器

Http 類型連接器：保有現有Http的相關操作，處理授權以及接口表達，通過集成平臺的網關進行轉發

托管類型連接器：用戶操作層面不變（Http協議），集成平臺內部實現具體動作，構建連接器管道，網關請求的時候會識別當前連接器的類型，以及規范路由從而進入連接器的管道，實現對應連接器的托管實現

? ? ? ? ? ? ? ? ? ? ? ? ? ? ?例如：數據庫連接器，把這種非Http協議的連接器，對外轉化成統一的Http協議接口，數據庫連接器提供了兩個接口-》查詢和寫入，用戶調用只需要通過接口的形式，最終操作集成平臺的連接器實現

Http連接器接口示例：和托管連接器對外實現接口描述一致

基于Http連接器，系統提供自發現&OpenApi 2.0,3.0規范文檔的導入實現

背景

大多數用戶存在很多這種Http協議的微服務，或者某個服務有很多接口， 用戶本身也需要對接口進行表達，并提供使用方調用；現使用集成平臺，如果手動添加，或者我們提供一種新的規則導入形式都會給用戶帶來不小的維護成本，基于種種考慮和用戶的真實訴求，集成平臺按照國際規范提供基于OAS規范的文檔導入，可以給用戶減少數據的維護操作，增加便利；下面介紹集成平臺的實現邏輯。

1、自發現

用戶在創建連接器的時候，系統會自動掃描連接下面的swagger頁面，獲取頁面中對應的json文件地址，讀取并解析，然后把每個Api拆分成單個OpenApi規范的json文檔進行存儲

示例：

2、導入功能

用戶可以填寫json文檔地址，或者上傳json文件，提交服務端，讀取并解析，然后把每個大的json文檔拆分成單個Path組成的OpenApi規范的json文檔進行存儲

示例：

3、集成系統對API的描述呈現

新建或者自發現或者導入， 在系統存儲中，每個Api是一個OpenApi 3.0規范的json文檔，頁面上面每個Api的詳情，即為解析json做界面渲染

組件實現基礎介紹

集成平臺后端技術主要為net core框架，作為OpenApi規范創始成員之一的微軟，對Core框架提供了相對成熟的擴展組件

Microsoft.OpenApi -》提供基于OpenApi規范的構建能力等

Microsoft.OpenApi.Readers-》提供基于OpenApi規范json文檔的讀取轉化能力，以及把對象轉發成json字符串的能力等

源碼：https://github.com/Microsoft/OpenAPI.NET

構建示例

var document = new OpenApiDocument{ Info = new OpenApiInfo { Version = "1.0.0", Title = "Swagger Petstore (Simple)", }, Servers = new List<OpenApiServer> { new OpenApiServer { Url = "http://petstore.swagger.io/api" } }, Paths = new OpenApiPaths { ["/pets"] = new OpenApiPathItem { Operations = new Dictionary<OperationType, OpenApiOperation> { [OperationType.Get] = new OpenApiOperation { Description = "Returns all pets from the system that the user has access to", Responses = new OpenApiResponses { ["200"] = new OpenApiResponse { Description = "OK" } } } } } }};br

集成平臺連接中心Http連接導入功能

實現模式：系統中對接口的描述，每個接口都會有一個獨立的文檔描述，什么叫獨立，獨立是指一個OpenApi規范文檔的最小粒度，一個Path一個文檔

? ? ? ? ? ? ? ? ? 所以我們實現的時候，把一個大的文檔，按照Path切割成若干的小文檔，并對單條數據進行填充，轉化成關系型的數據，例如一個接口會包含：請求類型，名稱，請求路徑等

流程示意圖

核心邏輯演示說明：主要分5步

1、通過地址或者文件讀取內容成文本

using (var httpClient = _httpClientFactory.CreateClient()) { string jsonStr = await httpClient.GetStringAsync(address); }文件讀取：using (StreamReader reader = new StreamReader(fileStream)) { string jsonStr = await reader.ReadToEndAsync(); }br

2、通過微軟提供的組件讀取文本，轉化成對象

OpenApiDocument openApiDocument= new OpenApiStringReader() .Read(jsonStr, out diagnostic)；//說明：diagnostic為OpenApiDiagnostic, 輸出值為版本號：2.0或3.0 // 來源nuget庫-》Microsoft.OpenApi.Readers // OpenApiDocument 來源nuget庫-》Microsoft.OpenApi// OpenApiStringReader 來源nuget庫-》Microsoft.OpenApi.Readersbr

3、遍歷文檔的Path，構建粒度最小的OpenApi規范文檔，一個Path對應一個文檔

/// <summary>/// 拆分文檔,并組裝數據/// </summary>/// <param name="list">解析文檔成結構化以及主要信息平鋪的對象集合</param>/// <param name="openApiDocument">原始的大Document</param>/// <param name="connectionCode">連接編碼</param>public static void ConverterSplit(List<ConnectionApiModel> list, OpenApiDocument openApiDocument, string connectionCode){ //校驗文檔的有效性 if (openApiDocument?.Paths == null || openApiDocument.Paths.Count < 1) return; foreach (var item in openApiDocument.Paths) { //構建Document對象 var docmentEntity = OpenApiOperExtensions.InstantiationSimplified (item.Value.Operations?.FirstOrDefault().Value?.Summary, openApiDocument?.Info?.Version ?? INFO_VERSION, item.Value.Operations?.FirstOrDefault().Value?.Description); //增加單path docmentEntity.AddPath(item); //增加當前Path涉及的Components docmentEntity.AddComponents(openApiDocument.Components, item.Value); //增加當前Path的Security docmentEntity.AddSecuritySchemes( openApiDocument.Components?.SecuritySchemes); //增加默認Schema - 非必須 docmentEntity.AddDefaultSchema(); //解析document對象為文本并添加list對象 Generate(docmentEntity, list, item, connectionCode);}br

構建Document說明

public static OpenApiDocument InstantiationSimplified(string title, string version, string description) { return new OpenApiDocument { Info = new OpenApiInfo { Title = title, Version = version, Description = description }, Paths = new OpenApiPaths(), Components = new OpenApiComponents() }; }br

添加Path說明

public static void AddPath(this OpenApiDocument openApiDocument, KeyValuePair<string, OpenApiPathItem> path) { ArgNullCheck(openApiDocument); if (openApiDocument.Paths == null) { openApiDocument.Paths = new OpenApiPaths(); } if (openApiDocument.Paths.ContainsKey(path.Key)) return; openApiDocument.Paths.Add(path.Key, path.Value); }br

增加SecuritySchemes說明

授權的SecuritySchemes為所有接口公用，拆分過程中，只需要每個最小粒度的文檔包含即可。

增加Components

找出當前Path引用的Components，當前操作會稍顯麻煩，在真實操作的時候單個Path的參數引用模型是可以是嵌套的模式，在獲取當前Path的Ref引用（引用會在Components包含）需要遞歸操作。

4、組裝Api數據，并把單條文檔轉化成json字符串，便于存入數據庫

RequestPath = 解析當前Path的路由Swagger = 當前Path的規范文檔（json）ConnectionCode = 連接器業務編碼（用戶側填寫）ApiName = 接口名稱（解析Path的Summery屬性得到）Description = 接口描述（解析Path的Description屬性）HttpMethod = 請求類型（解析Path的請求類型）

5、入庫

集成平臺連接中心Http連接導出功能

導出即為導入逆向的操作， 把多個單Document，聚合成一個大的OpenApi規范的Document，進行導出

導出邏輯不做代碼演示，和導入動作類似，需要建立新的Document，解析所有需要導出的接口數據，并把接口的規范文檔（json存入）通過微軟組件對象化，組裝成一個總的Json文檔，進行輸出即可。

總結

導出的邏輯可以各自思考一下

本文章主要想對連接器的導入導出結合OAS規范文檔做一些說明

希望大家對OAS規范文檔有個初步認識，對集成平臺連接器的導入和導出結合OAS規范文檔的實現能得到一些收獲

參考文章

https://github.com/fishead/OpenAPI-Specification/blob/master/versions/3.0.0.zhCN.md

https://en.wikipedia.org/wiki/OpenAPI_Specification

https://spec.openapis.org/oas/v3.0.3

https://swagger.io/specification/

https://github.com/Microsoft/OpenAPI.NET

------ END ------

作者簡介

孫同學：?研發工程師，目前負責集成平臺相關研發工作。

也許您還想看：

技術分享｜Java SDK動態數據源和上下文機制

技術分享｜NodeJS分布式鏈路追蹤實現

更多明源云·天際開放平臺場景案例與開發小知識，可以關注明源云天際開發者社區公眾號：

【建?！课臋n服務提供高保真打印模式

明源云·天際硬核技術認可：獲華為鯤鵬技術認證書

天際·開發者社區“重裝發布”！

總結

以上是生活随笔為你收集整理的集成开放平台标准化连接器之基于OAS3.0的API管理能力的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。