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