前言
本文主要介紹了一種新的開發思路：通過反轉開發順序，直接從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-design