如何真正實作由文檔驅動的API設計？

前言

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