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

一、OAS 3.0 初識(shí)

介紹

OAS 3.0即：OpenAPI Specification 3.0.*；OpenAPI 規(guī)范 為 REST API 定義了一種標(biāo)準(zhǔn)的、與編程語言無關(guān)的接口描述，它允許人類和計(jì)算機(jī)發(fā)現(xiàn)和理解服務(wù)的功能，而無需訪問源代碼、附加文檔或檢查網(wǎng)絡(luò)流量. 當(dāng)通過 OpenAPI 正確定義時(shí)，消費(fèi)者可以使用最少的實(shí)現(xiàn)邏輯理解遠(yuǎn)程服務(wù)并與之交互。與接口描述為低級(jí)編程所做的類似，OpenAPI 規(guī)范消除了調(diào)用服務(wù)時(shí)的猜測(cè)。

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

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

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

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

2016 年 9 月，API World 大會(huì)向 SmartBear 頒發(fā)了 API 基礎(chǔ)設(shè)施獎(jiǎng)，以表彰其在 Swagger 上的持續(xù)工作。[11]

2017 年 7 月，OpenAPI Initiative 發(fā)布了其規(guī)范的 3.0.0 版。[12] MuleSoft是替代RESTful API 建模語言(RAML)的主要貢獻(xiàn)者，加入了 OAS 并開源了他們的 API 建模框架工具，該工具可以從 RAML 輸入生成 OAS 文檔。

變更版本

2.0 & 3.0 根節(jié)點(diǎn)屬性示意圖

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

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

OpenAPI 根對(duì)象

# OpenAPI 規(guī)范版本號(hào) openapi: 3.0.0# API 元數(shù)據(jù)信息 info:# 服務(wù)器連接信息 servers:# API 的分組標(biāo)簽 tags: # 對(duì)所提供的 API 有效的路徑和操作 paths:# 一個(gè)包含多種綱要的元素，可重復(fù)使用組件 components:# 聲明 API 使用的安全機(jī)制 security:# 附加文檔 externalDocs:?

Info 對(duì)象

# API 元數(shù)據(jù)信息 info:title: xx開放平臺(tái)接口文檔 # 應(yīng)用的名稱description: | 簡(jiǎn)短的描述信息，支持 markdown 語法。| 表示換行，< 表示忽略換行。version: "1.0.0" # API 文檔的版本信息termsOfService: 'http://swagger.io/terms/' # 指向服務(wù)條款的 URL 地址contact: # 所開放的 API 的聯(lián)系人信息name: API Support # 人或組織的名稱url: http://www.example.com/support # 指向聯(lián)系人信息的 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 對(duì)象

所有的 API 端點(diǎn)都是相對(duì)于基本 URL 的。例如，假設(shè) https://api.example.com/v1 的基本 URL 中，/users 端點(diǎn)指的是 https://api.example.com/v1/users。

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

Server 表示一個(gè)服務(wù)器的對(duì)象。這里通常填寫測(cè)試服務(wù)器或者生產(chǎn)服務(wù)器的 IP 地址、端口版本號(hào)等信息（指定基本 URL）。

# 服務(wù)器連接信息 servers:- url: https://development.gigantic-server.com/v1description: 開發(fā)服務(wù)器- url: https://staging.gigantic-server.com/v1description: 測(cè)試服務(wù)器- url: https://api.gigantic-server.com/v1description: 生產(chǎn)服務(wù)器

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

Tag 對(duì)象

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

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

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

Path 對(duì)象

定義各個(gè)的端點(diǎn)和操作的相對(duì)路徑。這里指定的路徑會(huì)和 Server 對(duì)象?內(nèi)指定的URL地址組成完整的URL地址，路徑可以為空，這依賴于 ACL constraints 的設(shè)置。

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

External Documentation 對(duì)象

允許引用外部資源來擴(kuò)展文檔

# 附加文檔 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 對(duì)象

包含開放API規(guī)范固定的各種可重用組件。當(dāng)沒有被其他對(duì)象引用時(shí)，在這里定義定義的組件不會(huì)產(chǎn)生任何效果

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

詳細(xì)節(jié)點(diǎn)說明參考：https://github.com/fishead/OpenAPI-Specification/blob/master/versions/3.0.0.zhCN.md#oasDocument

基于OAS 規(guī)范制作文檔?

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

實(shí)用過程中，服務(wù)如何基于OpenAPI規(guī)范產(chǎn)生文檔以及可視化界面

具體項(xiàng)目實(shí)現(xiàn)可參考：

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

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

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

項(xiàng)目集成組件之后呈現(xiàn)示例：

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

服務(wù)需要對(duì)外表達(dá)和描述一個(gè)接口，集成平臺(tái)涉及接口管理的也需要進(jìn)行表達(dá)和描述，其中接口中心和連接中心對(duì)接口的表達(dá)以及文檔的存儲(chǔ)都為基于OpenApi規(guī)范的json文檔，下面描述連接中心模塊，如下

示例圖：

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

Http 類型連接器：保有現(xiàn)有Http的相關(guān)操作，處理授權(quán)以及接口表達(dá)，通過集成平臺(tái)的網(wǎng)關(guān)進(jìn)行轉(zhuǎn)發(fā)

托管類型連接器：用戶操作層面不變（Http協(xié)議），集成平臺(tái)內(nèi)部實(shí)現(xiàn)具體動(dòng)作，構(gòu)建連接器管道，網(wǎng)關(guān)請(qǐng)求的時(shí)候會(huì)識(shí)別當(dāng)前連接器的類型，以及規(guī)范路由從而進(jìn)入連接器的管道，實(shí)現(xiàn)對(duì)應(yīng)連接器的托管實(shí)現(xiàn)

? ? ? ? ? ? ? ? ? ? ? ? ? ? ?例如：數(shù)據(jù)庫連接器，把這種非Http協(xié)議的連接器，對(duì)外轉(zhuǎn)化成統(tǒng)一的Http協(xié)議接口，數(shù)據(jù)庫連接器提供了兩個(gè)接口-》查詢和寫入，用戶調(diào)用只需要通過接口的形式，最終操作集成平臺(tái)的連接器實(shí)現(xiàn)

Http連接器接口示例：和托管連接器對(duì)外實(shí)現(xiàn)接口描述一致

基于Http連接器，系統(tǒng)提供自發(fā)現(xiàn)&OpenApi 2.0,3.0規(guī)范文檔的導(dǎo)入實(shí)現(xiàn)

背景

大多數(shù)用戶存在很多這種Http協(xié)議的微服務(wù)，或者某個(gè)服務(wù)有很多接口， 用戶本身也需要對(duì)接口進(jìn)行表達(dá)，并提供使用方調(diào)用；現(xiàn)使用集成平臺(tái)，如果手動(dòng)添加，或者我們提供一種新的規(guī)則導(dǎo)入形式都會(huì)給用戶帶來不小的維護(hù)成本，基于種種考慮和用戶的真實(shí)訴求，集成平臺(tái)按照國際規(guī)范提供基于OAS規(guī)范的文檔導(dǎo)入，可以給用戶減少數(shù)據(jù)的維護(hù)操作，增加便利；下面介紹集成平臺(tái)的實(shí)現(xiàn)邏輯。

1、自發(fā)現(xiàn)

用戶在創(chuàng)建連接器的時(shí)候，系統(tǒng)會(huì)自動(dòng)掃描連接下面的swagger頁面，獲取頁面中對(duì)應(yīng)的json文件地址，讀取并解析，然后把每個(gè)Api拆分成單個(gè)OpenApi規(guī)范的json文檔進(jìn)行存儲(chǔ)

示例：

2、導(dǎo)入功能

用戶可以填寫json文檔地址，或者上傳json文件，提交服務(wù)端，讀取并解析，然后把每個(gè)大的json文檔拆分成單個(gè)Path組成的OpenApi規(guī)范的json文檔進(jìn)行存儲(chǔ)

示例：

3、集成系統(tǒng)對(duì)API的描述呈現(xiàn)

新建或者自發(fā)現(xiàn)或者導(dǎo)入， 在系統(tǒng)存儲(chǔ)中，每個(gè)Api是一個(gè)OpenApi 3.0規(guī)范的json文檔，頁面上面每個(gè)Api的詳情，即為解析json做界面渲染

組件實(shí)現(xiàn)基礎(chǔ)介紹

集成平臺(tái)后端技術(shù)主要為net core框架，作為OpenApi規(guī)范創(chuàng)始成員之一的微軟，對(duì)Core框架提供了相對(duì)成熟的擴(kuò)展組件

Microsoft.OpenApi -》提供基于OpenApi規(guī)范的構(gòu)建能力等

Microsoft.OpenApi.Readers-》提供基于OpenApi規(guī)范json文檔的讀取轉(zhuǎn)化能力，以及把對(duì)象轉(zhuǎn)發(fā)成json字符串的能力等

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

構(gòu)建示例

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

集成平臺(tái)連接中心Http連接導(dǎo)入功能

實(shí)現(xiàn)模式：系統(tǒng)中對(duì)接口的描述，每個(gè)接口都會(huì)有一個(gè)獨(dú)立的文檔描述，什么叫獨(dú)立，獨(dú)立是指一個(gè)OpenApi規(guī)范文檔的最小粒度，一個(gè)Path一個(gè)文檔

? ? ? ? ? ? ? ? ? 所以我們實(shí)現(xiàn)的時(shí)候，把一個(gè)大的文檔，按照Path切割成若干的小文檔，并對(duì)單條數(shù)據(jù)進(jìn)行填充，轉(zhuǎn)化成關(guān)系型的數(shù)據(jù)，例如一個(gè)接口會(huì)包含：請(qǐng)求類型，名稱，請(qǐng)求路徑等

流程示意圖

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

1、通過地址或者文件讀取內(nèi)容成文本

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

2、通過微軟提供的組件讀取文本，轉(zhuǎn)化成對(duì)象

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

3、遍歷文檔的Path，構(gòu)建粒度最小的OpenApi規(guī)范文檔，一個(gè)Path對(duì)應(yīng)一個(gè)文檔

/// <summary>/// 拆分文檔,并組裝數(shù)據(jù)/// </summary>/// <param name="list">解析文檔成結(jié)構(gòu)化以及主要信息平鋪的對(duì)象集合</param>/// <param name="openApiDocument">原始的大Document</param>/// <param name="connectionCode">連接編碼</param>public static void ConverterSplit(List<ConnectionApiModel> list, OpenApiDocument openApiDocument, string connectionCode){ //校驗(yàn)文檔的有效性 if (openApiDocument?.Paths == null || openApiDocument.Paths.Count < 1) return; foreach (var item in openApiDocument.Paths) { //構(gòu)建Document對(duì)象 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); //增加當(dāng)前Path涉及的Components docmentEntity.AddComponents(openApiDocument.Components, item.Value); //增加當(dāng)前Path的Security docmentEntity.AddSecuritySchemes( openApiDocument.Components?.SecuritySchemes); //增加默認(rèn)Schema - 非必須 docmentEntity.AddDefaultSchema(); //解析document對(duì)象為文本并添加list對(duì)象 Generate(docmentEntity, list, item, connectionCode);}br

構(gòu)建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說明

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

增加Components

找出當(dāng)前Path引用的Components，當(dāng)前操作會(huì)稍顯麻煩，在真實(shí)操作的時(shí)候單個(gè)Path的參數(shù)引用模型是可以是嵌套的模式，在獲取當(dāng)前Path的Ref引用（引用會(huì)在Components包含）需要遞歸操作。

4、組裝Api數(shù)據(jù)，并把單條文檔轉(zhuǎn)化成json字符串，便于存入數(shù)據(jù)庫

RequestPath = 解析當(dāng)前Path的路由Swagger = 當(dāng)前Path的規(guī)范文檔（json）ConnectionCode = 連接器業(yè)務(wù)編碼（用戶側(cè)填寫）ApiName = 接口名稱（解析Path的Summery屬性得到）Description = 接口描述（解析Path的Description屬性）HttpMethod = 請(qǐng)求類型（解析Path的請(qǐng)求類型）

5、入庫

集成平臺(tái)連接中心Http連接導(dǎo)出功能

導(dǎo)出即為導(dǎo)入逆向的操作， 把多個(gè)單Document，聚合成一個(gè)大的OpenApi規(guī)范的Document，進(jìn)行導(dǎo)出

導(dǎo)出邏輯不做代碼演示，和導(dǎo)入動(dòng)作類似，需要建立新的Document，解析所有需要導(dǎo)出的接口數(shù)據(jù)，并把接口的規(guī)范文檔（json存入）通過微軟組件對(duì)象化，組裝成一個(gè)總的Json文檔，進(jìn)行輸出即可。

總結(jié)

導(dǎo)出的邏輯可以各自思考一下

本文章主要想對(duì)連接器的導(dǎo)入導(dǎo)出結(jié)合OAS規(guī)范文檔做一些說明

希望大家對(duì)OAS規(guī)范文檔有個(gè)初步認(rèn)識(shí)，對(duì)集成平臺(tái)連接器的導(dǎo)入和導(dǎo)出結(jié)合OAS規(guī)范文檔的實(shí)現(xiàn)能得到一些收獲

參考文章

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

作者簡(jiǎn)介

孫同學(xué)：?研發(fā)工程師，目前負(fù)責(zé)集成平臺(tái)相關(guān)研發(fā)工作。

也許您還想看：

技術(shù)分享｜Java SDK動(dòng)態(tài)數(shù)據(jù)源和上下文機(jī)制

技術(shù)分享｜NodeJS分布式鏈路追蹤實(shí)現(xiàn)

更多明源云·天際開放平臺(tái)場(chǎng)景案例與開發(fā)小知識(shí)，可以關(guān)注明源云天際開發(fā)者社區(qū)公眾號(hào)：

【建模】文檔服務(wù)提供高保真打印模式

明源云·天際硬核技術(shù)認(rèn)可：獲華為鯤鵬技術(shù)認(rèn)證書

天際·開發(fā)者社區(qū)“重裝發(fā)布”！

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。