基於OAS設計可擴展OpenAPI

隨着互聯網行業的興起,開發模式已逐步轉換爲微服務自治:小團隊開發微服務,然後通過Restful接口相互調用。開發者們越來越渴望能夠使用一種“官話”進行流暢的溝通,甚至實現多種編程語言系統的自動化交互。
開放API戰略(Open API Initiativev)於2017年1月發表聲明,2月發佈實現草案,經過反覆討論, 標準API規範OAS(OpenAPI-Specification)3.0版本在2017年6月誕生。

OAS 3.0架構中將OpenAPI賦予了以下8個模塊的定義,其中×××模塊爲必選字段,綠色模塊爲可選字段:
基於OAS設計可擴展OpenAPI
各個主要模塊工作流如下所示:
基於OAS設計可擴展OpenAPI
以下重點說明用戶獲取使OAS API信息的三個必選部分:

2.1 API基本信息
用戶查詢獲取OpenAPI的基本定義及信息,涉及以下兩個模塊內容:

 openapi
是否必選:必選
對象類型:String
類似於XML聲明(<?xml version="1.0"?> ),用於設定文件應該使用哪一種規範進行解析。

 info
是否必選:必選
對象類型:Info Object
這個模塊主要提供API的元數據。
以下爲一個Info Object樣例:
title: Sample Pet Store App #必須,應用名稱
description: This is a sample server for apetstore. #應用的描述
termsOfService: http://example.com/terms/ #應用的服務條款連接
contact: #應用提供商的聯繫方式
name: API Support
url: http://www.example.com/support
email: [email protected]
license: #應用所遵循的協議
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1 #應用版本

2.2 目標服務器信息
用戶查詢獲取服務器的基本定義及信息,涉及以下模塊信息:
servers
是否必選:必選
對象類型:[Server Object]
這個模塊主要提供和目標服務器的連接信息,如果這個模塊沒有定義url,根據規範會自動生成一個url爲/的Server Object。
例如:
servers:

2.3 API路徑及定義
查詢API具體參數,涉及OAS剩餘的模塊,本文主要介紹paths和components模塊。

 paths
是否必選:必選
對象類型:Paths Object
這個模塊主要提供OpenAPI所在的目標服務器的連接信息,如果這個模塊沒有定義,根據規範會自動生成一個url爲/的Server Object。通過多級定義,分別確定API的paths/method,並且通過$ref引用comonents模塊中的定義,可以複用響應碼等相關信息。對於攜帶body體的請求類型,requestBody可以提供example(或數組examples),這是非常靈活的(可以傳入一個完整的例子,一個參考,甚至是一個URL的例子)。
例如:
/pets: #URL
get: #方法,get/post/..
description: Returns all pets . #描述
responses: #響應模塊
'200': #返回碼爲200,可以使用通配符定義響應
description: A list of pets. #響應描述
content: #Content字段
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/pet' #引用componets

 components
是否必選:非必選
對象類型:Components Object
這個模塊主要提供每個OpenAPI自定義的字段定義,這部分定義的對象往往被paths中具體API進行引用:
− 響應 responses
− 參數 parameters
− 示例 examples
− 請求體 requestBodies
− 標題 headers
− 鏈接 links
− 回調 callbacks
− 模式 schemas
− 安全體系 securitySchemes
以下爲一個Components Object樣例:
components:
schemas: #協議定義
Category:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
Tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
parameters: #參數定義
skipParam:
name: skip
in: query
description: number of items to skip
required: true
schema:
type: integer
format: int32
limitParam:
name: limit
in: query
description: max records to return
required: true
schema:
type: integer
format: int32
responses: #返回信息定義
NotFound:
description: Entity not found.
IllegalInput:
description: Illegal input for operation.
GeneralError:
description: General Error
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralError'
securitySchemes:
api_key:
type: apiKey
name: api_key
in: header
petstore_auth: #認證定義
type: oauth2
flows:
implicit:
authorizationUrl: http://example.org/api/oauth/dialog
scopes:
write:pets: modify pets in your account
read:pets: read your pets

3 如何使用OAS 設計可擴展的OpenAPI
OpenAPI規範包含一組有關如何設計REST API的強制性準則,首推協議優先的方法,而非實現優先,因此需要首先設計API接口,然後實現協定接口的代碼。
如何實現一個優雅的API是一個非常具有挑戰性的工作,開發者需要在龐大的後端系統的支持下,通過合適的方式將API暴露出去,除去單詞拼寫,路徑設計等以外,設計優良的OpenAPI往往具有以下特性:

 單一職責
單一職責是軟件工程中一條著名的原則,實際在設計API時應確保每個API具有單一核心的職責,當某個API職責發生改變時不應該導致其他API發生故障和風險。OAS中不同的API可以在paths模塊中引用多個schema,當我們設計新的API或者擴展原有API功能時,如果發現多個API多次引用相同schema,需重點審視每個API是否仍然保持單一職責。

 抽象API
合適的抽象API 與業務無關的,更通用,而且方便擴展。 具體的API接口設計能解決特定的問題,但是在系統的擴展性和普遍適用性上則相應欠缺,因此需要針對特定的場景分析,避免over-designed(過度設計)和under-engineering(懶惰設計)。
舉個簡單的例子,我們設計一個paths爲/dog的API,那麼這個API返回的是具體dog的相關信息,而如果我們進行抽象設計一個paths爲/pet的API,將dog作爲參數配置在components的parameters中,這樣該API的擴展性進行了提升,後續擴展其他寵物比如cat的業務可以在不改變API路徑的基礎上進行開發,只需要更新component的parameters即可。

 收斂API
提供給用戶的OpenAPI最好支持批量數據處理,而不是讓用戶一次一次地調用。通過考慮多個API間的關聯性,讓用戶體會到API的簡潔性。舉例來說,如果用戶有可能在調用 API2之前需要API1的結果,那麼API提供者應該把API1和API2進行包裝。這會減輕用戶的記憶負擔,API收斂需要符合最少知識的原則,作爲用戶應該對他所使用的系統有最少的瞭解,而不是過多介入到系統的細節中,因此在設計API時候,在滿足用戶訴求的情況下,components模塊字段越少越好。設計者往往容易在收斂API時候出現無法保證單一職責的原則的情況,好的設計需要在兩者之間取得一個平衡,聚焦於最終的目的:讓使用者快好省的用起來。

 擴展機制
在設計API時需要考慮未來可擴展性,爲後續API兼容歷史API提供支持。一方面便於開發者自身增加功能,另一方面用戶也能參與進來,共建API生態。通過設計定義OAS,可以方便的按照OAS架構設計出面向對象、擴展性良好的API。

 版本控制
版本控制其實是擴展的一部分,鑑於大量項目在版本控制方面都做的比較糟糕,諸如隨心所欲的版本命名、前後格式不一致的版本設定、沒有規範的功能迭代,因此在大版本號不變的情況下,需要保障API向前兼容。當API的大版本號改動時,意味着API整體有大的改動,很可能不兼容之前的API,同時可以提醒用戶需要查詢API更新文檔進行適配,否則用戶可能在更新API之後出現各種各樣難以預測的故障。反之,如果修改小版本號則意味着這是個向前兼容的優化升級,用戶可以在例行更新中採用新的API。這種和用戶約定好的默契,可以激發用戶採用新版本的熱情,而不是永遠不升級依賴。

 面向擴展開發
在通過OAS定義完相關信息之後,優雅的OpenAPI在開發過程中應着重思考API的可配置性,API的實現應該面向修改開放的,因此需要將相關諸如參數校驗、字段長度等配置項進行抽取,在提供默認配置項的前提下可配置可修改,同時應當允許配置項的新增,例如引入java的可變參數類型等,這樣當OAS文檔進行修改時,可以儘可能的較少整體API實現的變動量。
以上列舉了優雅的OpenAPI所具有的部分特性,與其說OAS設計規範是一個強制的法則,不如說是一種引導式框架,開發者通過遵循規範從而實現高效的敏捷迭代。
當完成OpenAPI的設計開發之後,我們需要將API託管到合適的平臺上進行能力開放,優秀的平臺減少API提供者的工作量,抽取公共能力使API提供者更加專注於業務功能開發。華爲雲的API網關集成了監控、流控、負載均衡等一系列功能,可以爲開發者提供高性能、高可用的API 託管服務,實現個人、企業API能力的快速開放。
關於API網關的詳情,可以點擊下面鏈接進行體驗:
https://console.huaweicloud.com/apig/?region=cn-north-1#/apig/expdemo

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章