API 環境正在快速成長。組織比以往更依賴連線的網路服務和整合，供應商有機會大幅增加其 API 的採用率。
開發人員希望使用易於學習且符合預期的 API。高品質的文件可以設定期望、教育使用者，並吸引開發人員開始使用您的服務進行新專案。
以下是一些讓您的團隊設計一流文件的方法
1. 講述一個大故事
當有人第一次出現查看您的 API 文件時，他們會看到什麼？
如果您嘗試推動採用並建立固定使用者群，您應該講述一個故事。文件可能會有不好的名聲，因為它通常是技術性的且詳盡的，但對於許多公司來說，文件現在既是產品的包裝，也是使用說明書。
您的故事是什麼？您的 API 消費者在故事中扮演什麼角色？例如，漫威有一個公開的 API，可讓開發人員查詢漫畫書的經典內容。
漫威 API 文件：https://developer.marvel.com/docs
當有人進入入口網站時，故事非常清楚：「用世界上最棒的漫畫 API 創造令人驚嘆的東西」。
您組織的 API 可能不依賴超能力，但可能有一個故事可以講述您的優勢，並讓開發人員對使用您的 API 感到興奮。
2. 提供明確的起點
好的，您已經用一個引人入勝的故事團結了您的新使用者。接下來呢？
提供明確的起點，讓開發人員知道從哪裡開始熟悉您的 API。熱門訊息工具 Slack 的 API 文件在這方面做得很好。他們用動態標題「建構：出色的機器人」講述故事，並以「從這裡開始」部分介紹他們的側邊導覽。
Slack API 文件：https://api.slack.com/
在有人向下捲動之前，他們就有一個明確的地方可以開始了解 API，這也讓 Slack 有一個專門的地方可以為新使用者設定期望。「從這裡開始」部分與標準的軟體開發生命週期一致，從規劃、設計到建構。考慮哪種結構最適合您的 API，但請務必在新使用者第一次瀏覽您的文件時為他們提供指導。
3. 建立一個促進常見使用案例的結構
除非開發人員只是單純瀏覽，否則他們在瀏覽您的文件時，可能已經有一個專案在腦海中。透過標示您的 API 可以支援的最常見使用案例或動作，您可以減少開發人員找到所需資訊的時間。Slack 在這方面也做得很好，在首頁標示出「傳送訊息」、「建立簡單工作流程」和「建構機器人」等動作。
花時間考慮您的最終使用者嘗試建構哪些類型的東西，以及您如何提前向他們提供所有最有用的資訊。如果您可以讓他們的第一個 API 專案變得簡單，您會增加他們定期回來的可能性。
4. 首先為人類撰寫
有些開發人員可能永遠不會在您的文件之外與您的組織互動。如果您的文件都是臨床且枯燥的，開發人員可能會找到他們需要的東西，但體驗不會突出。考慮您文件的語氣。是口語化的嗎？
如果開發人員坐在您旁邊，您會如何解釋驗證選項？
您需要值得信賴，因此請不要過度使用俚語或走極端，但也不要枯燥和隱晦。若要開始，您可能需要透過可讀性計算器執行您現有的文件。
這些計算器會讓您保持誠實，並突顯您可能有冗長句子或太多長字的部分。編碼已經夠難了；閱讀應該很容易。
5. 使其全面
開發人員對供應商的 API 文件期望很高。在我們的2019 年 API 狀態報告中，我們要求受訪者選擇「您在 API 文件中尋找的 5 個最重要的事項」。以下是來自 3,000 多名軟體專業人員的結果
請務必在您提供給消費者的資源中盡可能詳盡。想像一下最投入的使用者可能會瀏覽您的文件，不要讓缺乏文件阻礙他們。
這並不代表要用所有可能的資訊淹沒使用者。在您的文件中採用層級結構，以便輕量級使用者可以快速使用常見的使用案例，而進階使用者可以點擊詳細資訊，盡情瀏覽。
6. 使其具有互動性
在上表中，受訪者選擇「範例」作為 API 文件中最重要的組成部分。開發人員希望盡快親自動手，看看您的 API 有哪些可能性。
透過互動式文件，開發人員可以快速測試不同的 API 呼叫。我們前面提到的漫威入口網站有這個選項。當您建立帳戶時，會自動提供 API 金鑰。您可以使用該金鑰對所有不同的端點進行呼叫，並測試不同的操作。這個互動式頁面也有助於開發人員熟悉他們應該會看到的參數和錯誤訊息。
漫威互動式文件：https://developer.marvel.com/docs
7. 使用 OpenAPI 規格標準化您的 API 設計
OpenAPI 規格（以前稱為 Swagger 規格）是 REST API 的 API 描述格式，它已迅速成為業界標準。在我們的2019 年 API 狀態調查中，我們發現近 70% 的受訪者目前使用 Swagger/OpenAPI 標準來定義其 API。
此格式的設計易於學習，並且人類和機器都可讀取。
透過以一致的方式建構您的 API，您的組織能夠為開發人員提供一致的體驗。他們會知道會發生什麼以及在哪裡找到它。
採用 OpenAPI 規格的組織可以利用 SwaggerUI 等開放原始碼工具，自動將其 API 定義轉換為互動式文件。
您可以透過造訪 Swagger Petstore 來了解 SwaggerUI 的文件運作方式：https://petstore.swagger.io/
SwaggerUI 以及所有其他的開源 Swagger 工具，都可以在一個名為 SwaggerHub 的中心平台上取得。如果您的團隊正尋求將 OpenAPI 規範標準化，您可以建立一個免費帳戶，並立即開始匯入您的 API。
8. 強調教學、常見問題和案例研究
您的文件是您 API 的學習平台。
您可以解釋如何使用您的 API，但展示如何使用 API 真的可以讓它活起來。為簡單的專案類型建立教學，然後在您的文件中連結到它們。以下來自 Slack 的範例顯示他們正在建立和推廣的文章和教學類型，以幫助使用者了解他們的 API。
Slack API 教學：https://api.slack.com/tutorials
他們也列出了一些案例研究。為了真正推動您的 API 的採用，您不僅應該教育訪客，還應該為他們提供新專案的靈感。
Slack 引用的一個創意範例是 Kip，一個企鵝主題的機器人，可以幫助協調辦公室的食物訂購。透過強調一些最具創意的用戶，讓開發人員輕鬆了解您的 API 可以實現什麼。
9. 鼓勵使用者提供回饋
您的文件有多有效？
您可以查看不同的指標作為替代，例如頁面瀏覽量、消費者或呼叫次數，但單獨使用這些指標，您的團隊只能做出一些假設。
您可以調查使用者並了解他們的想法，但如果沒有將請求使用者回饋納入您的流程或基礎架構中，可能難以保持自律。最好的文件會鼓勵使用者在文件內提供回饋。
熱門支付供應商 Stripe 在這方面做得很好，他們在文件中的每個章節末尾都會詢問「這個章節有幫助嗎？」使用者只需在瀏覽時點擊「是」或「否」即可，非常省時。
透過詢問這個問題，他們可以清楚地看到哪些章節被標記為最沒有幫助，哪些章節有最多參與的訪客，然後相應地優先進行改進。
Stripe API 文件：https://stripe.com/docs/api
這個元素為您提供了現有文件的量化衡量標準，但您仍然不知道可能缺少什麼。透過結合內嵌的量化衡量標準和定性調查，您可以很好地了解文件的狀態。
10. 保持文件更新
閱讀只會讓事情更混亂的文件真的很令人沮喪。
如果您的文件沒有更新，可能會對您的組織產生不良影響，並阻止開發人員與您的 API 互動。
在我們的 2019 年 API 狀態報告中，我們詢問受訪者「提供最新的 API 文件最大的障礙是什麼？」前 3 個回應是
- 由於工作量而缺乏時間和/或資源
- 對交付速度的需求不斷增加
- 缺乏工具或技術
為了應對這些挑戰，您的團隊必須依賴可以加速流程並節省時間的工具。我們已經提到像 SwaggerUI 和 SwaggerHub 平台這樣的工具如何為您的 API 定義自動產生文件。
除此之外，尋找會減慢您團隊速度的相依性。您的文件團隊是否必須等待開發工作完成才能開始？
等待其他團隊完成工作會造成可避免的時間緊縮，並隨後損害文件的品質。
如果您的團隊正在使用 OpenAPI 規範，像 ServiceV Pro 和 VirtServer 這樣的工具可以輕鬆地將您的 API 設計轉換為可以在團隊之間共享的虛擬服務。
您的文件、開發和測試團隊都可以使用虛擬服務並行工作。透過專案的單一共享真實來源，您可以開始準確地記錄預期的回應，而無需等待其他團隊。
如果您的團隊正在使用 SwaggerHub，則與 ServiceV 有一個簡單的整合，使虛擬化成為您工作流程的自然部分。
了解更多關於 API 文件的資訊
想閱讀更多關於文件最佳實務的資訊嗎？以下是一些我們最喜歡的關於這個主題的文章，其中許多文章都為本文提供了資訊。去看看吧！
閱讀更多