前言

本文主要介紹了一種新的開發思路：通過反轉開發順序，直接從API文件中閱讀程式碼。作者認為通過這種開發方式，你可以更清楚地知道文件表達出什麼以及它應該如何實現。

如果單從API文件出發，由於資訊量不足，通常很難了解它具體想實現的功能，正因為有這種假設的存在，使得經常在開發之後才會想起對文件進行完善。但這種習慣對於任何開發人員而言，都不是一個好事情，在一個專案中他們會被分配完成不同的任務，不管是什麼任務，必須要準確理解每個功能後，才能找到合適的方法完成工作，而一份完善的文件的作用就是能讓你更好的理解具體的任務。

我們面對專案驗收不斷臨近的截止日期，更不得不將精力全都放在開發上，導致幾乎沒有時間處理和完善專案文件，一般只會寫個大概。因此，當你發現了文件上十分簡略的資訊時，那隻能寄希望於回憶起當時的開發細節，不然驗收時根本無從說起。

如果在驗收的標準中，對文件的完整度和正確性提出要求，並且使用者能對此進行評級，那文件的完善程度將會大大提升。

在編寫大量程式碼之前，如果已經在文件中記錄了所需的詳細資訊，那麼這個文件將成為開發團隊的寶貴資源。因為這個文件可以在開發團隊和測試人員之間共享，所有人都可以同時使用這樣的API。反過來說，通過團隊的互動性凸顯了文件在API開發中的重要位置。

當你想找到某一個文件時，通過互動協作的方式，你能夠直接從專案中呼叫這個文件，這將有助於開發人員在完成任務時更方便地呼叫API​​，有效減少開發人員除錯介面的時間。

我們知道了API文件的重要性，下面我們講一下文件設計應該如何設計。

3個API文件設計中重要功能

這些是我認為在文件中應該存在的三個功能：

1.時刻保持同步性，這意味著如果開發過程中增加了什麼內容，那麼從文件中也應該馬上得知，即便是進度滯後，也應該保證文件內容在即將釋出時與開發進度是一致的。

2.文件內容應該提供專案整個功能的完整內容，同時實現的方法也應該記錄在文件中，供開發人員回看，方便查漏補缺。

3.文件應該作為指導和規範，幫助不同分工的開發人員完成目標統一的業務，也可用於測試API，並有助於增強開發團隊溝通。如果有條件的話，還可以對完善文件的人提供獎勵。

基本的API文件部分

如何驗證API使用者的身份呢？首先你需要一個身份資訊驗證方案。

1.如果你使用的是OAuth，請不要忘記在文件中解釋如何設定OAuth並獲取API金鑰。

2.你需要記錄開發中遇到的錯誤以及它們導致的問題，你應該在文件中解釋這個錯誤是否違反了錯誤標準，即失敗示例。

3.你需要記錄包含端點和有關如何使用它們的資訊，包括請求資訊和返回資訊。這是API文件的最主要部分。

記錄好這三個部分，你將有一個良好的開端，因為你已經有了使用API所需的大部分內容。同時對於測試人員來說，根據你的文件進行API測試會方便很多。

但這往往還是不夠的，當你遇到更復雜的情況，你還得提供額外的API的非功能性方面的文件來補充說明。

API文件還應包含哪些內容

1.解釋API文件中每個引數作用。

2.各種語言和工具（cURL，Postman等）的API呼叫示例。這些示例可能會被多次使用，可以說是API文件中最重要的部分。

3.詳細說明呼叫API時的工作流程。

4.API提供程式採用的設計原則概述，例如REST（特別是超媒體），HTTP程式碼等。

5.有關身份驗證的資訊，包括可能實現的其他方案，如OAuth或OpenID Connect。

6.有關錯誤處理的一般資訊以及有關HTTP返回碼的資訊。

7.一種互動式API資源管理器，允許開發人員輕鬆地將所有這些資訊變為現實。

開始撰寫你的API文件

首先要將每個功能的需求轉換為文件，同時你的文件應該是可分享的。只有這樣，檢視的人可以通過文件獲得有關如何正確開發專案的資訊，尤其是需要理解文件以解釋專案的內部開發人員。

在編寫API專案的文件之後，如果有條件的話，最好將文件的書面註釋和其他內容轉換為豐富多彩的網站和其他可自定義的模板，將有助於為專案生成完整的站點。

3 個API文件模板標準

在所有API文件格式中，其中有三種值得一提，因為它們允許你以手動或者自動的方式設計API：

1.Swagger和Open API。你可以輕鬆生成自己的API伺服器程式碼，客戶端程式碼和文件本身。Open API Initiative（OAI）專注於基於Swagger規範建立，發展和推廣供應商中立的API描述格式。

2.RAML。RESTful API建模語言系統提供了一種能指定API使用模式的簡便方法。

3.API Blueprint。這是一種基於Markdown格式的標準，可讓你輕鬆地從文件中生成程式碼。

除了作者提到的三種API標準外，EOLINKER也支援自動讀取程式碼註解生成API文件，極大地提高了開發者文件撰寫的效率，有興趣的試試 EOLINKER API Studio，我這裡就不多說了，方正效率的確提升了很多！https://www.eolinker.com

總結

作為開發者，如果你想保證他人能夠很好地理解你的API，那麼在開發中就必須清楚文件的重要性。雖然有些人也承認上述的觀點，認為使用API文件啟動專案是一個好主意，但實際上大多數人都還在努力編寫與文件無關的內容。

如果一開始就規劃好你的文件，一旦確定後，那麼會有更多的時間來處理主專案的內容。從長遠來看，擁有優秀的文件可以為你節省大量時間，並可以幫助你更輕鬆地構建專案。

原文作者：Guy Levin

翻譯和修改：隔壁王書

原文地址：https://dzone.com/articles/documentation-driven-api-de