如何做到API文件規範化

小Kit發表於2023-04-06
API

定義一個好的 API 文件是優秀研發人員的標準配置，在執行介面測試之前，測試人員一定會先拿到開發給予的介面文件。

測試人員可以根據這個文件編寫介面測試用例，優秀的文件可以區分好的使用者體驗和壞的使用者體驗。它不僅可以幫助最佳化工作流程，還可以幫助前端工程師和測試工程師更好的規劃自己的任務。作為一名網際網路程式設計師，我們應該學習如何高效的輸出一份優秀的 API 技術文件。

首先我們需要了解介面文件的主要構成及含義，完整的介面文件有公共資訊說明、請求響應、介面簽名 DEMO、加簽程式碼示例、介面功能說明、介面引數詳細說明 5個部分組成。

1、公共資訊說明：

公共資訊說明頁為公共引數說明及請求受理結果程式碼兩部分：公共引數說明填寫多個介面提取的通用引數，這裡可以分為請求引數及影響引數。需要填寫引數名稱，型別，最大長度，描述和用法。請求受理結果程式碼就是影響碼的說明。

2、請求，相應及加簽 DEMO

請求，響應及加簽 DEMO 頁，一般這個頁面會描述加簽的過程，例如分為 rsa 加簽私鑰和服務引數說明。服務引數需要進行以下說明:

  1. 對引數名進行從小到大的排序

  2. 對引數及引數值拼接成字串

  3. 用 RSA 對引數串進行加簽後用 base64 編碼，獲得簽名串

  4. 對各個引數值進行引數值特殊字元的轉義

  5. 請求體說明

3、加簽程式碼示例

加簽程式碼示例部分會填寫加簽的程式碼例項，測試人員可以根據加簽程式碼編寫測試程式碼。

4、介面功能說明

介面功能說明填寫各介面的重要資訊，包含藉口名稱，介面型別，介面服務程式碼，介面版本號，備註。

5、介面引數詳細說明

介面引數詳細說明填寫介面的主要資訊及引數資訊。主要資訊有服務名稱，服務程式碼，服務版本號，服務功能描述，服務提供方系統，服務消費方系統。引數說明可分為描述，型別，子段長度，是否必填，說明。

透過以上我們可以讀懂介面文件也是介面測試的重要環節。透過對工作中介面文件的詳解，指導測試人員如何理解介面文件，進而透過介面文件編寫介面測試用例。


API 文件的重要性

API 文件是人類和機器可讀的技術內容，用於解釋特定 API 的工作原理及其功能。它的目的是雙重的。如果做得正確的話，API 文件將成為 API 工作方式的一個真正資訊來源。它應該以結構化格式包含函式、引數、類等的詳細資訊，便於開發人員和非技術使用者理解。通常，它包括教程和示例，幫助使用者更好地理解不同部分如何協同工作。

由於有許多不同型別的文件，很難使事情井然有序。API 需要參考、指南和其他內容來幫助開發人員。另外 API 支援的產品可能需要自己的參考資料，包括螢幕截圖和影片。


什麼是好的 API 文件？

一個好的 API 文件，除了內容合理詳細之外，它的樣式和互動方式也要簡單易用。現在的 API 文件基本基於網頁來展現，利用網頁的顯示特性，有一些比較常見的設計方式。在這裡推薦一些適合作為 API 文件展現要素的一些最佳實踐。

許多流行的工具線上釋出他們的 API 文件，以便第三方開發人員可以輕鬆訪問它們。以下是這些文件如此有效的一些原因：

  1. 在文件中提供了示例程式碼，以便使用者可以看到API在實踐中是如何工作的

  2. 輕鬆找到常見問題的解決方案，以便忙碌的開發人員可以快速獲得所需的內容

  3. 不提供理解 API 及其工作方式之外的不必要資訊。當使用者忙於工作並遇到問題時，他們需要可用的文件，而不是無關的資訊

  4. 不需要設限知識水平；最簡單的概念和最困難的概念一樣得到充分解釋

格式良好。內容有條理且一致且易於閱讀。這減少了希望學習或解決問題的使用者的摩擦。


文件的工具要求

想要一個工具來處理所有型別的文件是很自然的。考慮 API 文件，通常需要與工程團隊協作。將API文件硬塞進幫助文件平臺可能行不通。工程團隊處於版本控制中，例如 Git，因此即使是複製貼上到 CMS 的手動過程也無法完成。隨著工程對 API 進行更改，文件需要隨之更改，生成 API 參考將確保避免許多潛在的麻煩。


最佳的編寫方式

編寫 API 文件的方式不僅一種，不同的軟體有不同的使用規範，這些規範都各自提供了描述 API 的不同標準和風格，以下三四種僅為參考：

  1. OpenAPI（以前稱為 Swagger）–最受歡迎的規範。開源，並得到 Microsoft 和 Google 等公司的支援。使用具有特定架構的 JSON/YAML 物件來描述 API 元素。

  2. API Blueprint 另一個開放原始碼規範，API 藍圖旨在提供高度可訪問性。它使用類似於 Markdown 的描述語言，並且在 API 建立過程中遵循設計優先原則的情況下表現出色。

  3. RAML–基於 YAML 的 RAML（或 RESTful API 建模語言）採用自上而下的方法來建立清晰，一致和精確的文件。

  4. Eolink Apikit 以服務形式存在的介面文件，它可以伴隨程式碼的變更同步變化，這就減少了很多開發工程師和測試工程師之間的溝通成本。

這些編寫方式都可以應用於目前的工作，簡單、有⽤、可發現、⼀致、可預測，所有這些不僅描述了良好的 API，還描述了良好的產品。這不是偶然的，當你編寫 API 時，你將建立⼀個產品。


API 文件的可維護性

對於 API 文件的可維護性應該保持像維護一個單獨專案一樣，每次透過分支的形式進行更新，編輯人員在檢查文件內容的正確性和簡介性之後，並由專案組成員進行 review。當 API 文件釋出後，後期維護也是同等的重要，主要體現在兩個方面：

  1. New feature 和廢棄功能；當釋出新功能之前應該先發布文件，並保證文件透過了標準的review 流程。然而廢棄掉的舊功能從文件中移除，並建議在對應的位置給出廢棄功能提示和升級指南，確保使用舊功能的開發者進行升級工作

  2. 在文件頁面上應該預留文件的 contribute 入口，如果文件託管在 GitHub 這樣的平臺上就提供指向倉庫的連結，方便每個閱讀文件的使用者給文件提 Issue 或者 PR。如果文件是閉源的，也應該至少留有提供反饋資訊的位置


關於一些可用性建議

作為開發⼈員，我們很容易忽視這⼀點。根據知識的偏差，假設我們的 API ⽤戶是程式設計師，他們知道我們所知道的，理解我們所理解的，但我們並不認為他們是最終⽤戶或客戶。要克服這種偏差，換位思考是設計好的 API 的關鍵思想。所以當你編寫下⼀個 API 時，把⾃⼰放在客戶的⾓度，想象你想要的是什麼。

以上是對專案開發合作中寫出友好的 API 文件的一些想法和建議，歡迎討論。

相關文章