如何真正實現由文檔驅動的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