如今，各行各業的組織都意識到投資 API 程式的商業和策略機會。API 促進數位轉型，並為各種工程和商業可能性開啟大門。
但 API 經濟的成長也需要建構 API 的團隊有新的思考方式。如果終端消費者不了解使用 API 的價值，並且沒有可用的必要資源來開始使用它，即使是最好的 API 程式也會失敗。僅僅擁有 API 是不夠的；您還需要擁有出色的 API 開發者體驗。
什麼是 API 開發者體驗？
API 開發者體驗是一般使用者體驗 (UX) 的延伸。它是開發人員在與您的 API 互動時所擁有的所有體驗的總和。良好的 API 開發者體驗不僅僅是技術寫作。它是在於提供所有正確的資源，以幫助您的終端消費者了解並成功地使用您的 API。
為什麼 API 開發者體驗很重要？
在當今的現代軟體世界中，一般技術消費者在組織決定實施的工具和平台方面具有巨大的購買影響力。根據 Forrester 的首席分析師 Jeffrey Hammond 的說法，軟體團隊內的採用模式正在轉向開發人員，使他們有權阻礙或協助解決方案的採用。
這表示軟體產品的技術採用者現在是採用和購買產品的決策者。因此，讓技術採用者能夠輕鬆使用您的產品在當今超連結和競爭激烈的生態系統中至關重要，尤其是在 API 經濟中。
打造卓越 API 開發者體驗的秘訣
在提供出色的開發者體驗方面，沒有什麼可以取代高效能、易於使用的 API。開發者體驗始終從提供團隊想要使用、可以信任並安全整合的高可靠性 API 開始。
提供出色開發者體驗的關鍵要素是提供準確且最新的 API 文件。API 文件是成功使用和整合 API 所需的資訊。這可以是技術寫作、程式碼範例和範例的形式，以便更好地了解如何使用 API。
如今，一些最知名和廣泛使用的 API 背後的公司正在投資其 API 的豐富、人性化的文件。像 Facebook、YouTube、Microsoft、PayPal 和 DropBox 等公司（使用內部和公共 API 來推動技術協調和策略性成長）將文件置於其 API 開發者體驗的核心。
您如何開始您的 API 文件之旅？
為 API 團隊提供以文件為核心的出色開發者體驗，從未如此容易。雖然在過去，團隊必須依賴靜態形式的文件（如 PDF 或手動更新的網頁），但現在有解決方案可以自動化您的文件工作流程，並建立互動式 API 文件，使 API 的使用過程順暢且容易。
組織記錄其 API 的方式發生了重大變化。這些變化最明顯的地方莫過於 API 描述格式（如 OpenAPI 規格（前身為 Swagger 規格））的廣泛採用，它為產生美觀、互動式的 API 文件提供了基礎，讓終端消費者可以在無需將其實施到程式碼庫中的情況下與其互動。這種自動產生的文件是您的開發團隊可以自訂和建構的中央資源，以建立更全面的使用者手冊來使用您的 API。
在這本電子書中，我們將探討提供出色開發者體驗的各種因素，以及文件在其中的作用。我們將介紹 API 文件的最佳實務，並將探討您的團隊如何開始使用 Swagger 工具記錄您的 API，以及如何改善 SwaggerHub 中現有的文件工作流程。
讓我們開始吧！
規劃您的 API 開發者體驗
成功的 API 需要像公司產品組合中的任何一流產品一樣，受到同樣的關懷和重視。在處理 API 時應用產品管理原則是將您的 API 視為一流產品的第一步。在本節中，我們將介紹規劃 API 開發者體驗的 3 個重要步驟
- 了解 API 的目標受眾
- 了解 API 的採用歷程
- 將歷程對應到正確的受眾類型
了解 API 的目標受眾
正如我們之前強調的那樣，文件是您 API 的使用手冊。與任何產品一樣（是的，API 是產品），您需要從了解誰需要使用您的 API 文件開始。在下圖中，您將看到您的 API 文件潛在受眾的概述
您的 API 內容和文件最常見的消費者是需要直接整合和使用您的 API 的人員，以及想要評估並查看此 API 是否符合其開發和業務策略的人員。這些可以分為兩類
- API 使用者：想要與您的服務整合並希望使用您的 API 解決特定問題的開發人員。
- API 決策者：將評估您的服務並查看其是否解決策略性需求的人員。
當您開始細分 API 的受眾時，更容易了解您需要提供哪種類型的資源，以及這些資源應如何呈現。
了解 API 的採用歷程
您的受眾現在將經歷不同的階段，以發現和評估您的 API，然後才會完全投入您的服務。此使用者流程會將您的目標受眾從意識帶到最終熟悉並足夠舒適地使用您的 API 服務。設計良好的 API 將滿足此歷程每個階段的最佳開發者體驗。
下圖概述了使用者在採用您的 API 之前將經歷的關鍵階段。這些階段可以簡化為四個主要問題：
- 我為什麼要使用它？
- 我如何註冊使用它？
- 我從哪裡開始？
- 我該如何使用它？
請記住，受眾可能會重疊，但細分使用者歷程可讓您建立起點，以了解如何與參與採用 API 的不同人員進行溝通。
這些階段也利用了您組織內的不同角色。例如，前兩個階段更像是產品行銷的練習，重點在於溝通您服務的價值以及它們如何緩解現有的潛在客戶挑戰。當然，接下來的兩個階段純粹是技術寫作練習，其中技術寫作者需要產出內容，以幫助您的終端消費者了解並整合您的服務。
讓我們深入了解這些不同的階段。
「我為什麼要使用您的 API？」
這個階段的目標是為您的受眾提供服務概觀，使其能立即與他們想要完成的任務產生共鳴。API 使用者和評估者應該能夠快速理解您的 API 所提供的價值，以及他們如何開始使用它。這是目標受眾第一次與所呈現的資訊互動。為了以簡單有效的方式呈現這些資訊，您需要了解這些潛在客戶為何會接觸您的 API、他們如何發現您的服務，以及您的服務可以幫助解決哪些現有問題。以下是兩個在這方面做得很好的公司範例：
「我該如何註冊？」
一旦您說服 API 使用者和決策者，您的服務對他們可能具有價值，他們就會繼續他們的旅程。註冊流程是開始使用您的 API 服務的第一步。這個流程應該盡可能地簡單明瞭，但您也應該能夠取得有效管理這些使用者所需的資訊。一個策略是允許開發人員使用熱門的第三方服務（例如 Twitter 或 GitHub）註冊。透過這些服務，您可以輕鬆快速地擷取聯絡資訊，而無需讓他們經歷太多障礙。
如果您必須加入額外的步驟讓使用者註冊才能存取您的 API，請務必提供全面的文件和說明提示，以加速流程。一個糟糕的開發人員體驗範例是強迫使用者填寫冗長的表單，或在提供 API 金鑰之前要求不必要的詳細資訊。
「我該從哪裡開始？」和「我該如何使用它？」 
現在目標受眾已註冊存取您的 API，下一步是讓他們開始使用。
這些是開發人員體驗中，他們使用您的 API 服務的最後階段。他們希望親自動手操作您的 API 程式碼、試用它，並最終將其整合到他們自己的應用程式中。
引導他們完成這段旅程的秘訣是什麼？
出色的 API 文件。
文件是良好開發人員體驗的核心
簡潔明瞭的文件（可讓您的 API 使用者快速將其導入應用程式）對於希望推動 API 使用率的組織而言，已不再是可有可無的選項。
請考慮以下幾點
- 根據 SmartBear 的《2016 年 API 狀態報告》，現在有 75% 的開發 API 的組織具有正式的文件編寫流程。46% 的人表示這對他們的組織來說是一項高度優先事項。
- ProgrammableWeb 的一項調查發現，API 使用者認為完整且準確的文件是影響他們 API 決策的最大因素，甚至超過了價格和 API 效能。
良好的文件可加速開發和使用，並減少原本需要花費在回覆支援電話上的金錢和時間。重要的是要記住，文件對於內部 API 使用者也很重要。不要假設您的內部利害關係人會非常了解如何使用 API。
您的 API 文件中應該包含哪些內容？以下是一些在撰寫 API 文件時可能會對您有所幫助的提示。
提示 #1：列出基本要點
每個良好的 API 文件都必須包含某些部分。如果沒有這些部分，使用者將很難理解如何使用您的 API。
- 驗證。這是關於使用者開始使用您的 API 所需的驗證機制資訊。例如，如果您使用 OAuth，請不要忘了解釋如何設定 OAuth 應用程式並安全地取得 API 金鑰。
- 錯誤訊息。錯誤訊息很重要，因為您希望在以錯誤的方式與您的 API 服務整合時獲得回饋。解釋您的錯誤標準，並在終端使用者收到錯誤時，提供解決方案來克服這些錯誤。
- 端點以及如何使用它們的資訊。注意描述您的請求和回應週期。這些是使用者將與您的服務互動的主要 API 組件，因此請密切注意這一點。
- 使用條款。這是使用者與您的組織之間的法律協議，定義使用者應該如何理想地使用您的服務。這很重要，因為您希望確保開發人員和使用者遵守您組織建議的實務做法，而不是做出任何與您的企業價值觀相悖的事情。
- 在最佳實務做法中加入 API 限制，並附帶條款和條件。也需要清楚說明限制，以便使用者了解允許的 API 用法和實務做法。
- 變更日誌。詳細說明您的 API 更新和版本，以及這可能會如何影響 API 使用者。這將有助於使用者了解您的 API 的穩定性，並查看是否需要對有效的 API 呼叫進行任何變更。一旦您列出這些部分，就可以輕鬆地開始編寫文件，因為您的 API 現在已經有了一個很好的開始。
提示 #2：為人類撰寫
大多數 API 文件撰寫者都假設他們的文件受眾是 100% 的開發人員，或者是完全了解如何使用 API 的技術人員。但請記住，許多使用 API 的人可能不完全了解您可能使用的領域或術語。文件應該滿足 API 使用者（通常是開發人員）和相對不那麼技術性的 API 評估者（通常是產品經理和 CTO）的需求。
從為每個呼叫撰寫英文領域說明開始您的文件。避免使用太多技術術語，並以剛接觸 API 的人可以輕鬆理解的方式撰寫。
如果您確實有技術性或特定領域的術語，請將該特定項目連結到進一步說明這些術語的文件。這些策略將確保您的 API 具有清晰度和良好的結構，並說明為何存在某些呼叫，然後您才會在參數、標頭和回應的細節中迷失方向。
請考慮這個 Stripe API 文件的範例。他們在支援任何技術術語方面做得非常出色，並提供額外的內容來解釋這些術語。
提示 #3：說明您的請求-回應週期
您的 API 使用者應該確切知道成功的 API 呼叫會產生什麼結果。以每個支援的格式描述完整的範例回應主體。不僅要考慮 XML 或 JSON 等格式，還要考慮 HTTP 標頭、錯誤代碼和訊息。為終端使用者提供過多的資訊不會有問題，尤其是在他們嘗試將您的服務整合到他們的應用程式中時。
在您的 API 應該傳回的每個物件中提供範例，以及使用者可以為成功的 API 呼叫新增的參數範例。這是 Stripe 的另一個範例。終端使用者可以在文件開頭輕鬆了解每個錯誤代碼的確切含義。
提示 #4：實驗是力量
除了基本文件之外，團隊還應該提供額外的資源，以建立在他們提供給終端使用者的體驗之上。
- 入門指南：「入門」指南對於決定實作您的 API 的開發人員來說，可能是一個有用的下一步資源。此資源應提供更詳細的逐步說明，以快速使用 API。
- 互動式文件和主控台：您的受眾會希望在將您的 API 直接整合到他們的應用程式之前先試用它。提供沙箱或主控台，讓開發人員可以輕鬆部署和重設不同端點的回應，而無需篡改原始程式碼。
- SDK：一旦您的 API 發布，最好投資建立用戶端程式庫，讓終端使用者可以有效地使用您的 API。如果許多開發人員在您的服務中發現價值，他們甚至可能會為您建立 SDK。提供良好的開發人員體驗是培養開發人員社群的好方法。
- 教學課程：提供範例程式碼片段、範例 SDK 和良好的使用案例，以協助使用者了解您的服務。
使用 OpenAPI 的 API 文件
如今，全球數千個 API 團隊使用 OpenAPI 規格 (OAS) 和 Swagger 工具來為其內部和公開的 API 產生文件。
OpenAPI 規格概觀
OpenAPI 規格是一種機器和人類可讀的描述格式，用於定義 API 的合約。此合約定義了資源和服務公開的資料，以及用戶端應如何呼叫這些資源。雖然這個概念看起來很簡單，但在多平台 API 經濟中（其中服務以多種語言建構，並由不同裝置上的用戶端使用）具有強大的影響。
當 SmartBear Software 在 2015 年捐贈此規格時，它從 Swagger 規格重新命名為 OpenAPI 規格。它已成為 REST API 如何設計和文件的行業標準。將 OAS 實作到您的 API 工作流程中有很多實際用途，API 團隊最常見的 OAS 應用是產生精美的互動式文件，可以輕鬆地與 API 的終端使用者分享。
OAS 解決了團隊在處理 API 文件時面臨的兩個最大挑戰：
1. API 文件的維護
維護和更新您的開發團隊和終端使用者所使用的文件，以便他們可以有效地使用您的 API，可能是一個困難且繁瑣的過程。如果您使用靜態文件（例如 .PDF）向終端使用者提供文件，則尤其如此。OAS 可讓您為您的 API 定義合約，並使用 Swagger UI 或 SwaggerHub 等工具為該 API 自動產生互動式 UI。
該互動式 UI 可以作為您的團隊建立 API 文件的畫布，其中包含不同的範例、說明、錯誤訊息以及其他構成優秀 API 文件的詳細資訊。
2. 多重服務互動
API 需要一個通用的介面，以便在不同服務之間進行取用和互動。傳統的 API 介面，無論是文字文件或其他像是 Javadoc 的形式，都無法讓不同語言的服務之間進行互動。
使用 OAS 定義的 Web 服務可以彼此溝通，而無需考慮它們所使用的程式語言，因為它是與語言無關且機器可讀的。
使用 OAS 撰寫 API 文件
使用 OAS 撰寫 API 文件首先要產生一個初始的 OAS 合約，或稱「規格」，它構成了 API 設計和文件的基礎。以下是該合約的範例：
openapi: 3.0.0
info
title: 範例 API
description: 可選的多行或單行描述，使用 [CommonMark](http://commonmark.org/help/) 或 HTML。
version: 0.1.9
servers
- url: http://api.example.com/v1
description: 可選的伺服器描述，例如：主要（生產）伺服器
- url: http://staging-api.example.com
description: 可選的伺服器描述，例如：用於測試的內部測試伺服器
paths
/users
get
summary: 傳回使用者列表。
description: 可選的擴展描述，使用 CommonMark 或 HTML。
responses
'200': # 狀態碼
description: 使用者名稱的 JSON 陣列
content
application/json
schema
type: array
items
type: string
有兩種方法可以為您的 API 產生 OAS
- 設計優先：首先制定 OpenAPI 規格，然後將其轉換為人類和機器可讀的合約，例如 OpenAPI 定義，然後從該合約構建程式碼，並產生文件。
- 程式碼優先：基於業務計畫，直接編寫 API 程式碼，然後從中產生人類或機器可讀的文件，例如 OpenAPI 定義，然後再進行文件編寫。
這兩種方法都有其優缺點，最終選擇哪種方法取決於您希望使用 API 解決的當前技術和策略需求。
雖然設計優先的方法正在興起並獲得越來越多的採用，但如今大多數組織仍然遵循程式碼優先的方法。這些組織知道文件對其最終用戶的重要性，因此他們會使用第三方工具從現有的 API 產生 OpenAPI 定義，並使用 OpenAPI 定義，可以利用開源的 Swagger UI 或 SwaggerHub 等工具來產生互動式 API 文件。
為了幫助簡化這個過程，Swagger 團隊最近發布了一個新的工具來產生 OAS 定義 — Swagger Inspector。Swagger Inspector 是一個易於使用的開發人員工具，可以快速執行任何 API 請求、驗證其回應，並產生相應的 OpenAPI 定義。
讓我們從使用最新的 Swagger 工具之一 Swagger Inspector 來看看程式碼優先的方法如何運作。
使用 Swagger Inspector 產生 OpenAPI 定義
使用 Swagger Inspector，透過呼叫每個端點並選擇相關回應來產生符合 OAS 的文件，從而快速產生現有 REST API 的基於 OAS 的文件，或者將一系列呼叫串連在一起，以產生多個 API 端點的完整 OAS 文件。
無論您的團隊採用哪種 Swagger 方法，都需要進行一些工作來建立 API 文件。在大多數情況下，組織會依賴技術寫手來填寫文件。這包括新增有意義、易於理解的資訊，供您的最終用戶使用，以實現 API 的成功。根據此合約，可以使用 Swagger UI 產生互動式的文件版本。Swagger UI 允許任何人（無論是您的開發團隊還是最終用戶）視覺化 API 的資源並與之互動，而無需任何實作邏輯。
使用 Swagger Inspector 帳戶，您還可以為您呼叫的任何端點自動產生 OpenAPI 檔案，從而節省開發時間。Swagger Inspector 與 SwaggerHub (團隊 API 設計和文件平台) 緊密整合。這種整合允許開發人員在 SwaggerHub 上自動託管和視覺化其 API 文件，以使內部和外部利害關係人能夠發現和取用 API。
請依照下面的步驟開始。
如何從現有 API 產生 OpenAPI
前往 Swagger Inspector 並請求您要編寫文件的資源端點。然後，導航到 Swagger Inspector 右側的「歷史記錄」面板，然後按一下「建立 API 定義」以建立 OAS 定義。
Swagger Inspector 的出色之處在於集合功能。選取多個端點，並透過集合將其文件合併到一個單一的 OpenAPI 檔案中。
如果您已經有 SwaggerHub 帳戶，則可以使用這些憑證登入 Swagger Inspector。
產生的定義將為您的團隊提供符合 OAS 的結構，以建立您的 API 文件。有了定義後，您可以新增重要的詳細資訊，例如：支援的內容類型、描述、範例、驗證類型等。
接下來，我們將更詳細地說明如何在 SwaggerHub 中從此定義繼續建立您的 API 文件。
使用 SwaggerHub 增強 API 文件
如上文所述，API 文件並非易事。組織不僅需要進行技術寫作，還需要確保文件安全且易於使用。還有一些營運方面的考量，例如託管和維護，所有這些都會增加組織在金錢和時間方面的額外開銷。
這就是為什麼像 SwaggerHub 這樣的專用組織平台可以提供幫助的原因。SwaggerHub 是一個整合的 API 設計和文件平台，旨在協助團隊推動 API 開發工作流程的一致性和規範性。
SwaggerHub 的互動式文件以視覺方式呈現您的 OAS 定義，以便即時互動和操作，因此您的最終用戶可以在將其整合到其程式碼庫之前，確切地知道您的 API 將如何讀取和執行。
它是直接從 API 合約產生的，可以使用 SwaggerHub 編輯器從頭開始建立，也可以從您的檔案系統和原始碼控制主機匯入。
在 SwaggerHub 中入門有幾種不同的選項。如前所述，您可以使用 Swagger Inspector 產生 OAS 定義並匯入 SwaggerHub。
如果您要開始一個新的 API 專案，則 SwaggerHub 編輯器可讓您輕鬆開始設計新的 API。讓我們來看看一些可以幫助您的團隊入門的功能。
即時視覺化呈現
SwaggerHub 提供了一個功能強大的視覺化編輯器，用於使用 OAS 定義 API 的每個端點，讓 API 架構師和開發人員在編寫任何程式碼之前，了解使用者將如何與您的 API 互動。SwaggerHub 將文件放在您的 API 工作流程的中心，讓您可以自動產生 API 的互動式 UI，該 UI 會隨著對 API 合約所做的每次變更而更新。
安全、自動託管
SwaggerHub 消除了設定後端伺服器來託管 API 文件的需求。SwaggerHub 讓您可以將文件託管在一個集中的平台中，並輕鬆地將受控存取權限授予 API 的開發團隊或最終用戶。您可以從 SwaggerHub 內部公開提供文件，或將其設定為私人，並邀請內部團隊成員或合作夥伴進行安全共用。
最佳化、無混亂的工作流程
您的 API 設計和文件有多個利害關係人，而良好的協作是成功發布 API 的關鍵。透過嚴格控制將哪些更新新增到您的主要 API 工作流程中，更好地協同合作。協作者可以透過分叉主 API 來建立其副本、新增變更，並透過視覺化比較和合併功能將變更合併回主 API 工作流程中。當您的 API 發生變更時，您的團隊會立即收到電子郵件通知，並將其傳送到他們的收件匣。
引導式 API 開發人員入口網站
您的 API 開發人員入口網站是卓越開發人員體驗的自然延伸，其中包含文件和程式碼片段，以協助最終用戶理解和使用您的 API。讓您為開發人員入口網站產生的基本客戶端程式碼，並使用 SwaggerHub 的內建 HTML 入口網站產生器在其上構建。只需按一下，SwaggerHub 就會產生 HTML 範本，其中包含您的 API 文件和 6 個用戶端 SDK 使用範例，供您的開發人員入口網站使用，這使得您的開發團隊可以非常輕鬆地自訂、互動和使用。
維護和反覆運算
組織可以集中維護其所有 API 文件和相關版本。透過 SwaggerHub 的版本控制系統，逐步建立在現有的 API 文件之上，或維護多個生產 API 版本的文檔。透過在現有版本之上構建來發布穩定、運作中的 API 的文件，並優雅地棄用過時的版本。開發團隊可以自訂、互動和使用。
透過出色的 API 文件改善開發人員體驗
請記住，文件是 API 的使用手冊，並且是實現 API 業務目標的最大驅動因素之一。OpenAPI 規格和 Swagger 工具可減輕文件方面的擔憂，建立互動式、人類和機器可讀的文件，這些文件是自動產生的，並且只需要最少的維護。
建立消費者會喜歡的 API 文件需要付出努力，但這種投資將以出色的開發人員體驗、更輕鬆的實作以及 API 的採用率提高的形式獲得顯著回報。
SwaggerHub 負責處理所有基礎設施方面的考量和安全性實作，讓組織可以無縫協作並建立消費者和開發團隊都會喜歡的優質 API 文件。
超過 150,000 名 API 開發人員和組織信任 SwaggerHub 來協助改善其 API 文件工作流程。
了解 SwaggerHub 如何協助您的團隊。 立即免費開始使用。