使用OpenAPI構建更智能的API

像OpenAPI這樣的API描述規範是一個關鍵工具，您應該儘量地將其好好掌握，記錄和執行API的工做由計算機和開發人員完成；OpenAPI 3.0如今容許額外的表現力，可讓機器爲咱們作更多有用的工做；OpenAPI能夠驅動強大的測試自動化，它能夠用於生成模擬，它甚至能夠模擬進行本機綁定，從而讓開發人員中更能分析出其複雜性；您能夠利用OpenAPI的隱藏優點（如連接和回調）來使開發人員脫離文檔而直接經過代碼瞭解。本文主要介紹如何使用OPENAPI構建更智能的API。

不容置疑，現在已是API主宰的時代。即便是傳統而非技術公司（這樣單一產業的公司愈來愈少）也將API視爲關鍵產品。愈來愈多的公司使用API​​做爲溝通手段，這是不一樣團隊之間分享工做和溝通的基本單位。許多人試圖效仿亞馬遜的成功，亞馬遜的內部和外部API數量和質量都在不斷上升。在2020年即將重拍的電影《畢業生》中，導演對想要進行數字重建的年輕人達斯汀霍夫曼的一個建議是認可他的將來將是「API」。

這是我能夠挖掘的最引人注目的OpenAPI單行描述：「 機器可讀取到的接口文件的規範」。在這個標語口號的背後隱藏着一些很是實用的技術。是的，它容許您以機器可使用的方式描述您的API，可是機器能夠作的事情對於構建API的團隊以及使用它們的軟件開發人員來講很是有用。

熱切的學習者

當我仍是個孩子時，API引用法則被寫在書中，我開始細讀和熟悉它們。好比開發人員指南、Palm編程、Java 3D API規範等，那時蒂姆奧萊利（著名出版社）但是拿走我很多的書錢。這些書籍是你學習API如何運行的途徑，不只僅是關於你想要操做的系統或平臺，還有關於如何實現它的細節，和一系列API參考例子。這種學習資料分佈在在網絡上，咱們意識到須要一個平臺來教授全部人即使是熱心的學習者，教育咱們一個道理——構建它們的人和使用咱們構建的API的人同樣重要。

嚴格來講，專業術語「API」涵蓋了不少方面，因此在這裏爲了作統一，本文我將專一於的是基於HTTP的API。我稱之爲REST。Web API的數量正在之前所未有的速度激增，咱們私人服務器中的API愈來愈像用於雲服務的API，開放在互聯網上。我也不是在談論像WSDL這樣的古董，或者像GraphQL那樣的新熱點（雖然我稍後會談到它），只是幾乎每一個SaaS供應商都發布的API都是簡單易明的。

許多開發人員再也不須要生成代碼中實際存在的API接口，而是須要生成能夠提供由文檔、註冊信息、代碼生成等組成的編程描述。OpenAPI不是描述API的惟一規範，但確是一個優點彷佛愈來愈突出的標準。像AWS，Google和Palantir使用的是他們本身的API規範，通常由於他們的規範指定得較早，或者有不一樣的要求，或者甚至發現像OpenAPI這樣的規範的說法不夠充分。而我會傾向於OpenAPI，由於它的人氣飆升已經催生了大量的工具（包括咱們本身的API-SQL層）。

在OpenAPI中描述API是全部過程的第一步。咱們人工閱讀的文檔是一個明顯的輸出，但OpenAPI還讓咱們教育機器使用咱們的API來進一步簡化人工的事情並自主運做。隨着咱們向OpenAPI提供愈來愈多的信息，咱們能夠開始將人的工做轉移到他們使用的機器和工具上。某種意義上API是一種產品，能夠減小開發人員的重複工做量。

OPENAPI 101

能夠用JSON或YML指定OpenAPI文件，下面是Strava OpenAPI文檔的一個片斷：

"paths": {

"/athletes/{id}/stats": {

"get": {

"operationId": "getStats",

"summary": "Get Athlete Stats",

"description": "Returns the activity stats of an athlete.",

"parameters": [

{

"name": "id",

"in": "path",

"description": "The identifier of the athlete. Must match the authenticated athlete.",

"required": true,

"type": "integer"

},

{

"$ref": "#/parameters/page"

},

{

"$ref": "#/parameters/perPage"

}

],

"tags": [

"Athletes"

],

您可使用工具（或手動）編寫文檔，也能夠從代碼（使用幾乎任何語言）中生成文檔。下面是Java中的一個示例，其中包括OpenAPI註釋以及JAX-RS註釋。

@GET

@Path("/{username}")

@Operation(summary = "Get user by user name",

responses = {

@ApiResponse(description = "The user",

content = @Content(mediaType = "application/json",

schema = @Schema(implementation = User.class))),

@ApiResponse(responseCode = "400", description = "User not found")})

public Response getUserByName(

@Parameter(description = "The name that needs to be fetched. Use user1 for testing. ", required = true) @PathParam("username") String username)

throws ApiException {

User user = userData.findUserByName(username);

if (null != user) {

return Response.ok().entity(user).build();

} else {

throw new NotFoundException(404, "User not found");

}

}

OpenAPI的最好輸出是文檔。一個好處是（具備至關智能的工做流程）內容能夠保持最新，過期的文檔是使人尷尬和無助的。同時OpenAPI讓你的文檔變得更加漂亮。您能夠添加有用的組件（如交互式資源管理器）或自動生成更改日誌，而不只僅是描述API的輸入和輸出。

無需人工的干預，OpenAPI能夠驅動基於您所描述的內容發佈API的模擬服務器。這些模擬API能夠根據規範中的模式以及規範中代碼的特定示例進行響應。這樣，您的內部團隊就能夠在API徹底構建以前開始啓動，並容許外部開發人員測試API的使用，而不會向服務器發送垃圾郵件（或者在得到通過身份驗證的訪問以前）。

咱們最先使用OpenAPI的一個方法是生成本地代碼綁定。在咱們的例子中，咱們爲前端生成了TypeScript綁定，以便與後端進行交互。這將API學習過程從代碼和文檔移到了IDE中。咱們能夠依靠編輯器向咱們展現各類API的內容，包括正確的類型，而不是查看服務器代碼來弄清楚它是如何工做的。發佈API的OpenAPI規範容許開發人員使用代碼探索技術（若是你喜歡Vim）瞭解它。

OPENAPI3.0

OpenAPI計劃在一年多前發佈了3.0版本。它包括一些很是酷但仍未充分利用的功能。最重要的是，它擴展了描述API的能力。很高興看到OpenAPI在後續版本中增強了這一能力。3.0版還引入了兩個很酷的新元數據：LINKS和CALLBACKS。

LINKS（連接）

一般，API調用的結果能夠用做另外一個API調用的輸入。您甚至可能已經在其響應主體中看到了包含文字連接的API。OpenAPI的連接功能添加了描述不一樣API之間連接的靜態元數據，以及如何使用一個API的輸出做爲另外一個API的輸入。很高興看到更多的OpenAPI文檔使用連接和更好的工具來指定連接。

CALLBACKS（回調）

註冊webhook時，一般會將URL做爲字符串傳入，而後該服務將調用該API。OpenAPI 3.0容許您描述回調的簽名以及它應該具備的參數。再者，這很是有助於讓開發人員脫離文檔並經過代碼發現問題。

更多

採用OpenAPI減輕了API建立者的負擔，並試圖有效地教育他們的用戶，可是，當它讓開發人員不只學得更好而學習更快時，它就是最有效的。OpenAPI能夠作更多的工做來專一於教育開發人員使用的機器而不是開發人員本身。例如，考慮分頁。如下是Google Calendar API教會用戶對日曆事件進行分頁的方法：

輸入：

pageToken：Token specifying which result page to return

輸出：

nextPageToken：Token used to access the next page of this result. Omitted if no further results are available, in which case nextSyncToken is provided

仔細閱讀的話，能夠看出咱們應該從nextPageToken獲取輸出並將其插入到每一個連續調用的pageToken輸入中，可是在OpenAPI（或Google的專有發現文檔格式）中沒法表達該語義。

總結

若是您已構建API或正在構建新API，請開始使用API​​描述規範。OpenAPI是愈來愈受歡迎的選擇，但若是這對你不起做用的話，仍然會沿用選擇其餘的規範。當您能夠越多地停留在人跡罕至的道路上，您就會愈加現工具或者生態系統帶來的好處。

因而可知要構建更智能的API，有一個好的API編寫規範是十分重要的。因爲如今國內API市場產品衆多，可是功能良莠不齊，找到一個全面並且穩定的很難。最近發掘了一個新的工具：EOLINKER，他們是作API研發管理服務，有詳細的文檔編寫規則，頁面也很清晰，最重要是支持讀取代碼註釋生成文檔，並且還支持零代碼進行API測試。對API管理、監控等方面有興趣的小夥伴自行了解下哦！https://www.eolinker.com

如何開始使用OpenAPI（或相似的文檔規範）描述API的過程會遇到有爭議的選擇。對於契約優先的理論，API規範應該是API項目開始的地方，有一些經常使用的Web框架工具能夠從代碼中提取規範（在某些狀況下由附加的註釋或備註輔助）。

不管是契約優先仍是代碼優先，它實際上取決於您本身開發時的流程。對於大型組織而言，契約優先多是在同一頁面上明確地獲取服務器和客戶團隊的正確方法。在編寫服務器代碼時，客戶端團隊能夠針對自動生成的模擬進行編寫。對於客戶端和服務器一塊兒開發的或API自己就是產品的項目，代碼可能就足夠了。只有符合要求在這些狀況下，您能夠從常見的Web框架派生OpenAPI文檔（在某些狀況下，能夠藉助其餘註釋）。

如今您已經得到了API描述，您應該作的最重要的事情就是發佈它。發佈它，並使其保持最新。充分利用內部使用：生成服務器緩存和本地代碼，構建自動模擬，以及生成詳細的文檔。可是經過發佈API文檔，您能夠了解開發人員用來使用API​​的工具。他們今天能夠生成的示例，模擬測試意味着開發人員能夠花更少的時間來了解API的細節而且花充足的時間構建。隨着OpenAPI及其工具生態系統的發展，隨着他們使用的框架和平臺變得更加智能，API的做用正變得愈來愈全面。

原標題：Using OpenAPI to Build Smart APIs for Dumb Machines
做者：Adam Leventhal，Transposit的創始人兼首席執行官
原文連接：https://www.infoq.com/article...