幾乎所有的API參考主題都包括以下五個部分：

1. 資源說明 “資源”是指API返回的信息。
2. 終點和方法 端點指示您如何訪問資源，而方法指示與資源的允許的交互（例如GET，POST或DELETE）。
3. 參數 參數是您可以隨端點傳遞的選項（例如，指定響應格式或返回的數量）以影響響應。
4. 請求示例 該請求示例包括一個使用端點的示例請求，其中顯示了一些已配置的參數。
5. 響應示例和架構響應示例 顯示了來自請求示例的示例響應。響應模式定義了響應中所有可能的元素。

目錄

步驟1：資源說明

• 資源描述示例
• 描述資源的術語
• 認識參考文檔與用戶指南之間的區別

步驟2：端點和方法

• 端點示例
• 用花括號表示路徑參數
• 您可以在端點旁邊列出方法
• 端點僅顯示結束路徑
• 如何對同一資源的多個端點進行分組
• 如何在教程中引用端點

步驟3：參數

• 參數示例
• 四種參數
• 參數文檔中的注意事項
• 標頭參數
• 路徑參數
• 查詢字符串參數
• 請求正文參數

步驟4：請求示例

• 請求示例
• 多個請求示例
• 各種語言的請求
• 自動生成代碼樣本
• SDK為API提供工具
• API瀏覽器可與您自己的數據進行交互
• API Explorer在用戶手中可能很危險

步驟5：響應示例和架構

• 響應示例和模式的示例
• 您需要定義響應嗎？
• 在示例響應中使用實際值
• 格式化JSON並使用代碼語法突出顯示
• 記錄嵌套對象的策略
• 三欄式設計
• 嵌入動態響應
• 那狀態碼呢？

步驟1：資源說明

“資源”是指API返回的信息。大多數API具有可以返回的各種類別的信息或各種資源。

資源描述簡短（1-3個句子），通常以動詞開頭。資源通常具有各種端點來訪問資源，並且每個端點都有多種方法。在同一頁面上，通常會描述一個常規資源以及用於訪問該資源的許多端點。

資源描述示例

這是Mailchimp API Campaigns資源中資源描述的示例：

Campaigns資源描述示例

‌通常，API將在同一資源下分組多個端點。在這種情況下，您將描述常規資源和各個端點。例如，Campaigns資源具有各種端點，這些端點也進行了描述：

Campaigns資源端點示例

這是Box API中的Membership資源的資源描述：

Box API資源示例

‌對於成員資格資源（或稱其為“對象”），可以調用7種不同的端點或方法。Box API描述了成員資格資源以及使您可以訪問該資源的每個端點。有時沒有描述一般資源；相反，它只是將端點分組。大部分描述出現在每個端點中。例如，在Eventbrite API中，以下是“事件”資源：

Eventbrite API資源示例

‌儘管此處沒有描述“事件”資源，但已為每個“事件”端點添加了描述。事件資源包含所有這些端點：

Eventbrite端點示例

‌作為另一個示例，Instagram API的先前版本描述了一個Relationships資源，如下所示：

Instagram API資源示例

沒有描述“關係”資源，而是充當關係端點的容器。將為“關係”資源中分組的每個資源添加描述：

Instragram API 端點示例

‌有關具有資源和端點的API的另一個示例，請查看Trello API。

描述資源的術語

引用資源的確切術語有所不同。使用URL訪問的“事物”可以通過多種方式引用，但是“資源”是最常見的術語，因為您是通過URL或統一資源定位符訪問它們的。除了“資源”，您可能還會看到諸如API調用，端點，API方法，調用，對象，服務和請求之類的術語。一些文檔通過不明確地調用除“參考”之外的任何內容來避免這種情況。

儘管術語多種多樣，但通常API會通過“端點”訪問各種“資源”。端點使您可以訪問資源。（但是術語不是標準的，因此請多加註意。）

有關API術語如何變化的更多信息，請參見bunq API文檔中的資源，端點，對象和項目之間的區別。

認識參考文檔與用戶指南之間的區別

資源描述（以及端點描述）通常很短，通常為1-3個句子。如果要添加更多詳細信息怎麼辦？在這些情況下，請記住參考文檔和用戶指南/教程之間的區別：

• 參考文檔：開發人員可以快速參考的簡明信息。
• 用戶指南/教程：有關如何使用API​​的詳細說明，包括分步說明，代碼示例，概念和過程。我將在“記錄概念”部分中詳細介紹此內容。

‌儘管API參考主題中的描述提供了該資源包含的信息的1-3個句子的摘要，但是您可以在用戶指南中對此進行更詳細的擴展。（您可以將參考描述鏈接到指南中提供更多詳細信息的位置。）

步驟2：端點和方法

端點指示您如何訪問資源，而方法指示與資源的允許的交互（例如GET，POST或DELETE）。

同一資源通常具有各種相關的端點，每個端點具有不同的路徑和方法，但是返回有關同一資源的不同信息。端點通常具有簡短的描述，類似於總體資源描述，但簡短。此外，端點僅顯示資源URL的結束路徑，而不顯示所有端點共有的基本路徑。

1. 端點示例
2. 用花括號表示路徑參數
3. 您可以在端點旁邊列出方法
4. 端點僅顯示結束路徑
5. 如何對同一資源的多個端點進行分組
6. 如何在教程中引用端點

• ‌端點示例

這是Instagram API中Relationships資源的端點示例：

Instagram API端點示例

終結點通​​常以風格化的方式進行設置，使其更具視覺吸引力。許多文檔都是圍繞端點構建的，因此在文檔中賦予每個端點更多的視覺效果可能是有意義的。

端點可以說是API文檔最重要的方面，因為這是開發人員將用來實現其請求的內容。

用花括號表示路徑參數

如果端點中具有路徑參數，請使用花括號將其表示。例如，這是Mailchimp API的示例：

<code>/campaigns/{campaign_id}/actions/send/<code>

如果可以，請將path參數設置為另一種顏色以將其突出：

<code>/campaigns/{campaign_id}/actions/send/<code>

用戶會理解，路徑參數的花括號是一個慣例。在上面的示例中，幾乎沒有端點在實際路徑語法中使用花括號，因此{campaign_id}是一個明顯的佔位符。

這是來自Facebook API的示例，該示例以一種易於識別的方式為path參數著色：

Facebook API path參數著色示例

當在Facebook的文檔中描述參數時，使用相同的綠色來襯托參數，這有助於用戶識別其含義。

路徑參數並非總是以唯一的顏色設置（例如，某些顏色前面帶有冒號），但是無論採用哪種約定，請確保可以輕鬆識別路徑參數。

‌通常在端點旁邊列出方法（GET，POST等）。該方法使用資源定義操作。簡要地，每種方法如下：

• GET：檢索資源
• POST：創建資源
• PUT：在現有資源中更新或創建
• PATCH：部分修改現有資源
• DELETE：刪除資源有關

更多詳細信息，請參見維基百科有關HTTP的文章中的請求方法。（還有一些其他方法，但很少使用。）由於方法本身沒有太多要說的，因此將方法與端點歸為一組是很有意義的。這是Box API的示例：

Box API的請求方法示例

這是Linkedin API的示例：

端點僅顯示結束路徑

描述端點時，僅列出端點路徑（因此稱為“端點”）。包含基本路徑和端點的完整路徑通常稱為資源URL。

在我們的示例API場景中，端點僅為/ surfreport / {beachId}。您不必每次都列出完整的資源URL（即https://api.openweathermap.org/surfreport{beachId}）。包括完整的資源URL將分散用戶對重點路徑的注意力。在用戶指南中，通常會在介紹性部分（例如“入門指南”）中說明完整的資源URL以及所需的授權。

如何對同一資源的多個端點進行分組

記錄端點和方法時，另一個要考慮的問題是如何對端點進行分組和列出，特別是在您擁有大量相同資源的端點的情況下。在資源描述示例中，我們研究了各種API。許多文檔網站為將資源的每個端點分組或列出都提供了不同的設計，因此，我不會重複所有相同的示例。以某種有意義的方式對端點進行分組，例如按方法或按返回的信息類型。

例如，假設您有三個GET端點和一個POST端點，所有這些端點都與同一資源相關。一些文檔網站可能會在同一頁面上列出同一資源的所有端點。其他人可能將它們分成單獨的頁面。其他人可能為GET端點創建一個組，為POST端點創建另一個組。這取決於您對每個端點要說多少。

如果端點幾乎相同，則將它們合併在一個頁面上可能很有意義。但是，如果它們實質上是唯一的（具有不同的響應，參數和錯誤消息），則將它們分隔到不同的頁面可能會更好（並且更易於管理）。同樣，通過更復雜的網站設計，您可以在同一頁面上瀏覽冗長的信息。

如何在教程中引用端點

在教程和其他概念性內容中，如何在API參考主題中引用端點？提及“ / aqi endpoint”或“ / weatherdata”端點並沒有多大區別。但是，對於更復雜的API，使用端點來談論資源可能很棘手。

在我工作的一家公司中，我們用於Rewards端點的URL如下所示：

<code>/rewards/rewards/{rewardId}/users/{userId}/rewards/users/{userId}/rewards/{rewardId}/<code>

任務中的獎勵如下所示：、

<code>/users/{userId}/rewards/{missionId}/missions/{missionid}/rewards/<code>

說您可以使用獎勵資源並不總是那麼具體，因為存在多個獎勵和任務終點。

引用端點可能會很尷尬。例如，您可能會有這樣的句子：“當您調用/ users / {userId} / rewards /時，您將獲得所有獎勵的列表。為了獲得針對特定用戶的特定任務的特定獎勵，/ users / {userId} / rewards / {missionId}端點採用了幾個參數……”

端點越長，參考就越麻煩。這些描述在文檔的概念部分中更為常見。通常，對於如何引用繁瑣的端點並沒有明確的約定。採用最適合您的API的方法。

步驟3：參數

參數是您可以隨端點傳遞的選項（例如，指定響應格式或返回的數量）以影響響應。參數有四種類型：標頭參數，路徑參數，查詢字符串參數和請求正文參數。

通常在同一頁面上的不同組中記錄不同類型的參數。並非所有端點都包含每種類型的參數。

1. 參數示例
2. 四種參數
3. 參數文檔中的注意事項
4. 標頭參數
5. 路徑參數
6. 查詢字符串參數
7. 請求正文參數

參數示例

以下屏幕截圖顯示了Box API的示例參數部分：

Box API 參數示例

Box API的樣本參數

‌在此示例中，參數按類型分組：路徑參數，查詢參數和主體參數。端點還以可識別的方式在端點定義中設置了路徑參數（collab_id）。

‌很多時候，參數只是在表或定義列表中列出，如下所示：

Box API的樣本參數示例

您可以通過多種方式（除了表格外）格式化值。如果您使用的是定義列表或其他非表格格式，請確保開發出易於讀取的樣式。

‌四種參數

REST API具有四種類型的參數：

• 標頭參數：請求標頭中包含的參數，通常與授權相關。
• 路徑參數：端點路徑中查詢字符串（？）之前的參數。這些通常放在花括號內。
• 查詢字符串參數：端點查詢字符串中位於？之後的參數。
• 請求正文參數：請求正文中包含的參數。通常以JSON形式提交。

‌參數文檔中的注意事項

無論參數類型如何，請為每個參數定義以下內容：

• 數據類型
• 最大值和最小值

<strong>‌參數的數據類型

‌如果數據類型或格式錯誤，API可能無法正確處理該參數。列出數據類型通常對於所有參數類型都是一個好主意，但對於請求主體參數尤其如此，因為這些參數通常以JSON格式設置。

‌這些數據類型是REST API最常見的類型：

• 字符串（string）：字母和/或數字的字母數字序列整數：
• 整數（integer）-可以是正數或負數
• 布爾值（boolean）：真或假值
• 對象（object）：JSON格式的鍵值對
• 數組（array）：值列表

<strong>‌參數的最大值和最小值

除了指定數據類型外，參數還應指示最大值，最小值和允許的值。例如，如果天氣API僅允許特定國家/地區的經度和緯度座標，則應在參數文檔中描述這些限制。

忽略有關最大/最小值或其他不允許的值的信息是文檔中的常見陷阱。開發人員常常沒有意識到用戶使用API​​的所有“創造性”方式。質量保證團隊（QA）可能是識別不允許值的最佳資源，因為這是試圖破壞API的質量保證。

‌

標頭參數

‌標頭參數包含在請求標頭中。通常，標頭僅包含所有端點都通用的授權參數；因此，標頭參數通常不會記錄在每個端點上。相反，標頭參數中的授權詳細信息記錄在授權要求部分中。

‌但是，如果端點要求在標頭中傳遞唯一的參數，則可以在每個端點的參數文檔中記錄它們。

‌路徑參數

路徑參數是端點本身的一部分，不是可選的。例如，在以下端點中，{user}和{bicycleId}是必需的路徑參數：

<code>/service/myresource/user/{user}/bicycles/{bicycleId}/<code>

‌路徑參數通常用花括號引起來，但是某些API文檔樣式在該值之前加冒號或使用其他語法。在記錄路徑參數時，請指定默認值，允許值和其他詳細信息。

<strong>‌對路徑參數進行顏色編碼

當您在端點中列出路徑參數時，可以幫助對參數進行顏色編碼，使其更易於識別。對參數進行顏色編碼可以清楚地知道什麼是路徑參數，什麼不是。通過顏色，可以在端點和參數定義之間創建直接連接。

‌例如，您可以對參數進行顏色編碼，如下所示：

顏色編碼示例額

然後，您可以在以後的描述中為這些參數使用相同的顏色：

顏色編碼示例

通過對參數進行顏色編碼，可以很容易地看到所定義的參數及其與端點定義的關係。

‌

查詢字符串參數

查詢字符串參數出現在端點中的問號（？）後面。參數和它們的值後面的問號稱為“查詢字符串”。在查詢字符串中，每個參數都一個接一個地列出，並用＆分隔。查詢字符串參數的順序無關緊要。

例如：

查詢字符串示例額

和

查詢字符串示例

將返回相同的結果。但是，對於路徑參數，順序確實很重要。如果參數是實際端點的一部分（不在查詢字符串後添加），則通常在端點本身的描述中描述此值。

‌

請求正文參數

通常，對於POST請求（在其中創建內容），您需要在請求正文中提交JSON對象。這稱為請求正文參數，格式通常為JSON。此JSON對象可能是帶有多層嵌套的鍵/值對的冗長列表。

例如，端點可能很簡單，例如/ surfreport / {beachId}。但是在請求的主體中，您可能會包含一個具有許多鍵值對的JSON對象，如下所示：

請求正文參數示例

‌JSON數據（包括請求正文參數和響應）是API文檔中比較棘手的部分之一。如果對象很簡單，並且在同一級別只有幾個鍵/值對，則記錄JSON對象很容易。但是，如果您有一個JSON對象，其中的對象內部有多個對象，許多層的嵌套以及冗長的條件數據，則可能會很棘手。而且，如果JSON對象跨越100行或1000行以上，則需要仔細考慮如何呈現信息。

‌表格可以很好地記錄JSON，但是在表格中，很難區分頂級項目和子級項目。包含一個對象的對象也可能包含一個對象，另一個對象等可能會令人困惑。

‌無論如何，如果JSON對象相對較小，則表可能是您的最佳選擇。但是設計師也採用了其他方法。

‌看看eBay的findItemsByProduct資源。這是請求正文參數（在這種情況下，格式為XML）：

eBay API正文參數示例

在請求正文參數下方是描述每個參數的表格：

參數表格示例

但是樣本請求還包含指向每個參數的鏈接。在樣本請求中單擊參數值時，您會轉到一個頁面，該頁面提供有關該參數值的更多詳細信息，例如ItemFilter。由於參數值更復雜並且需要詳細說明，因此可能會有單獨的頁面具有更多詳細信息。

在其他請求中也可能使用相同的參數值，因此eBay的方法可能會促進重用。即使這樣，我也不喜歡跳到其他頁面來獲取所需的信息。‌

1. Swagger UI的請求body參數的方法

Swagger UI（我們稍後將進行演示，並進行演示）提供了另一種記錄請求正文參數的方法。Swagger UI以您在下面看到的格式顯示請求正文參數。Swagger UI使您可以在響應和請求正文參數的“示例值”和“模型”視圖之間切換。

Swagger UI的請求body參數示例

請參閱Swagger Petstore，在此處瀏覽演示。“示例值”顯示了語法示例以及示例。單擊“模型”鏈接時，您會看到一個示例請求正文參數以及每個元素的任何描述。

該模型包括帶有值的展開/摺疊開關。（Petstore演示在模型中並未包含許多參數描述，但如果包含描述，它們將顯示在模型中而不是示例值中。）

您會發現在請求正文參數中記錄JSON和XML的方式多種多樣。沒有正確的方式來記錄信息。與往常一樣，選擇以最清晰，最易讀的方式描述API參數的方法。

如果您的參數相對簡單，那麼選擇就沒有太大關係。但是，如果您有複雜，笨拙的參數，則可能必須訴諸自定義樣式和模板才能更清晰地呈現它們。我將在“響應示例和模式”部分中更深入地探討該主題。

步驟4：請求示例

該請求示例包括一個使用端點的示例請求，其中顯示了一些已配置的參數。請求示例通常不會顯示所有可能的參數配置，但是應儘可能豐富參數。

樣本請求有時包含代碼片段，這些代碼片段以多種語言（除了curl之外）顯示相同的請求。以其他編程語言顯示的請求是可選的，並不總是包含在參考主題中（但是，如果可用，用戶歡迎它們）。

• 請求示例
• 多個請求示例
• 各種語言的請求
• 自動生成代碼樣本
• SDK為API提供工具
• API瀏覽器可與您自己的數據進行交互
• API Explorer在用戶手中可能很危險

請求示例

以下示例顯示了來自Callfire API的示例請求：

Callfire API的示例請求

該API文檔網站的設計將示例請求和響應安排在三列布局的右列中。該請求以curl格式設置，我們在前面的“進行curl調用”中進行了探討。

<code>curl -u "username:password" -H "Content-Type:application/json" -X GET "https://api.callfire.com/v2/texts?limit=50&offset=200"/<code>

curl是一種常見的顯示請求的格式，其原因如下：

• curl與語言無關，因此它並不特定於一種特定的編程語言。
• curl顯示請求中所需的標頭信息。
• curl顯示了與請求一起使用的方法。

‌通常，使用curl來顯示您的樣品請求。這是Parse API中的curl請求的另一個示例：

Parse API中的curl請求示例

您可以在curl中添加反斜槓以將每個參數分隔到自己的行中（儘管，正如我在curl教程中指出的那樣，Windows在反斜槓方面遇到了麻煩）。

‌其他API文檔站點可能會使用完整的資源URL，例如Twitter的以下簡單示例：

Twitter API請求示例

資源URL包括基本路徑和端點。顯示完整資源URL的一個問題是，它不指示是否需要傳遞任何標頭信息來授權請求​​。（如果您的API僅包含GET請求，並且不需要授權，那麼很好，但是通過這種方式設置的API很少。）curl請求可以輕鬆顯示任何標頭參數。

‌多個請求示例

如果您有很多參數，請考慮包括幾個請求示例。在CityGrid Places API中，where端點如下：

CityGrid Places API多個請求示例

但是，從字面上看，您可以使用17個可能的查詢字符串參數。結果，該文檔包含幾個示例請求，這些請求顯示了各種參數組合：

參數組合示例

當通常不一起使用參數時，添加多個請求示例很有意義。例如，在少數情況下，您實際上可能在同一請求中包括所有17個參數，因此任何示例在顯示內容方面都會受到限制。

本示例說明如何“按字母順序查找波士頓的酒店，查看結果1-5”：

https://api.citygridmedia.com/content/places/v2/search/where?what=hotels&where=boston,ma&page=1&rpp=5&sort=alpha&publisher=test&format=json

如果單擊鏈接，則可以直接看到響應。在“響應”主題中，我將詳細介紹如何在用戶單擊請求時動態顯示響應。您應該顯示多少個不同的請求和響應？可能沒有簡單的答案，但可能不超過幾個。您決定什麼對您的API有意義。舉幾個例子，用戶通常會理解這種模式。

‌各種語言的請求

如前所述，在什麼是REST API中，REST API與語言無關。通用協議有助於促進跨編程語言的廣泛採用。開發人員可以使用任何語言編寫應用程序，從Java到Ruby到JavaScript，Python，C＃，Node JS或其他任何語言。只要開發人員可以使用該語言發出HTTP Web請求，他們就可以使用該API。Web請求的響應將包含JSON或XML數據。

由於您無法完全瞭解最終用戶將使用哪種語言進行開發，因此嘗試提供每種語言的代碼示例是徒勞的。許多API僅顯示提交請求的格式和示例響應，並且作者將假定開發人員將知道如何以其特定的編程語言提交HTTP請求。

但是，某些API確實會以多種語言顯示簡單的請求。這是Twilio的一個例子：

Twilio多語言顯示示例

您可以為示例請求選擇所需的語言：C＃，curl，Java，Node.js，PHP，Python或Ruby。這是Clearbit API的另一個示例：

Clearbit API的多語言顯示示例

您可以在Shell（curl），Ruby，Node或Python中查看請求。開發人員可以輕鬆地將所需的代碼複製到他們的應用程序中，而不用弄清楚如何將curl請求轉換為特定的編程語言。

‌提供通常通過標籤顯示的各種請求，有助於使您的API易於實現。如果您可以根據實際用戶的登錄個人資料自動用實際用戶的API密鑰填充API密鑰，那就更好了。

‌但是，不要為如此混亂的代碼示例所嚇倒。一些API文檔工具（例如Readme.io或SwaggerHub）可以自動生成這些代碼示例，因為使用不同編程語言發出REST請求的模式遵循一個通用模板。

‌自動生成代碼樣本

如果您不使用自動生成代碼示例的創作工具，並且想要提供這些代碼段，則可以根據需要從Postman和Paw中自動生成代碼示例。

Paw（適用於Mac）可讓您將請求導出為幾乎所有可能的語言：

Paw多語言轉換示例

配置請求後（類似於Postman的過程），可以通過轉到文件>導出請求來生成代碼段。Postman應用程序也可以類似的方式生成代碼片段。我在之前的有關從響應有效內容中檢查JSON的教程中介紹了此過程。在Postman中，配置請求後，單擊“代碼”鏈接（該鏈接顯示在右上方區域中“保存”按鈕的下方）。

Postman代碼轉換示例

然後選擇所需的語言，例如JavaScript> Jquery AJAX：

Postman代碼轉換示例

（有關涉及使用Postman生成的jQuery代碼的活動，請參閱從響應有效內容中檢查JSON，然後訪問Access並打印特定的JSON值。）

‌SDK為API提供工具

很多時候，開發人員會創建一個REST API附帶的SDK（軟件開發套件）。SDK可幫助開發人員使用特定工具來實現API。儘管API與語言無關，但SDK特定於語言。

例如，在我工作的一家公司中，我們同時擁有REST API和JavaScript SDK。由於JavaScript是開發人員使用的目標語言，因此該公司開發了JavaScript SDK，使使用JavaScript的REST更加容易。您可以通過JavaScript SDK提交REST調用，並傳遞許多與Web設計人員相關的參數。

SDK是可以簡化使用API​​的任何一種工具。對於一家公司來說，提供一種與語言無關的REST API，然後開發一個SDK，可以輕鬆地以他們希望用戶以其實現API的主要語言來實現該API，這是極為普遍的。其他語言的小請求摘要並不重要，因為SDK提供了更簡單的實現。如果您有SDK，則需要製作更詳細的代碼示例，以顯示如何使用SDK。

‌API瀏覽器可與您自己的數據進行交互

‌許多API都具有API資源管理器功能，該功能使用戶可以直接從文檔中發出實際請求。例如，這是Spotify API文檔的典型參考頁：

Spotify API文檔的典型參考頁

Flickr的API文檔還具有內置的API資源管理器：

Flickr的API文檔

和《紐約時報》 API一樣：

《紐約時報》 API

通過API Explorer，您可以將自己的值，自己的API密鑰和其他參數插入請求中，以便直接在API Explorer中查看響應。能夠看到您自己的數據使響應更加真實和即時。

但是，如果您的系統中沒有正確的數據，則使用您自己的API密鑰可能無法向您顯示完整的響應。當資源涉及公共信息並且請求是GET請求時，它效果最佳。

API Explorer在用戶手中可能很危險

儘管交互功能很強大，但是API資源管理器可能會危險地添加到您的站點中。如果嘗試DELETE方法的新手意外刪除數據該怎麼辦？以後如何刪除通過POST或PUT方法添加的測試數據？

允許使用GET方法是一回事，但是如果您包含其他方法，則用戶可能會無意中破壞其數據。在Sendgrid的API中，在使用其API Explorer測試呼叫之前，它們會向用戶發送警告消息：

Sendgrid的API Explorer示例

Foursquare的API文檔以前在其文檔的先前版本中具有內置的API資源管理器（如下所示），但此後已將其刪除。我不確定為什麼-也許他們遇到了其中一些問題。

就集成自定義API Explorer工具而言，對於開發人員而言，這是一項相對容易的任務。API Explorer所做的只是將字段中的值映射到API調用，並將響應返回到同一接口。換句話說，API管道就在那裡—您只需要一些JavaScript和前端技能就可以實現它。但是，您不必構建自己的工具。諸如Swagger UI（用於分析OpenAPI規範文檔）和Readme.io（允許您手動或從OpenAPI規範輸入詳細信息）之類的現有工具可以將API Explorer功能直接集成到文檔中。

步驟5：響應示例和架構

響應示例顯示了來自請求示例的示例響應。響應模式定義了響應中所有可能的元素。響應示例並不全面涵蓋所有參數配置或操作，但應與請求示例中傳遞的參數相對應。響應使開發人員知道資源是否包含他們想要的信息，格式以及該信息的結構和標記方式。

響應的描述稱為響應模式。響應模式以更全面，更通用的方式記錄響應，列出可能返回的每個屬性，每個屬性包含的內容，值的數據格式，結構以及其他詳細信息。

• 響應示例和模式的示例
• 您需要定義響應嗎？
• 在示例響應中使用實際值
• 格式化JSON並使用代碼語法突出顯示
• 記錄嵌套對象的策略
• 三欄式設計
• 嵌入動態響應
• 那狀態碼呢？

‌響應示例和模式的示例

‌以下是來自SendGrid API的示例響應。他們的文檔提供了一個選項卡式顯示，其中一個選項卡上有一個示例：

另一個選項卡上的響應模式：

響應的定義稱為模式或模型（術語同義使用），並且與JSON模式語言和描述保持一致。與SendGrid示例一起特別有效的方法是使用expand / collapse標籤來鏡像與示例相同的結構，並且對象處於不同的級別。

‌Swagger UI還提供了示例值和架構或模型。例如，在我用於SwaggerUI活動的示例Sunrise和Sunset Times API文檔中（本課程的後面部分），您可以看到響應示例和響應模式之間的區別。這是示例值：

示例響應應與示例請求相對應。正如請求示例可能只包括所有可能參數的子集一樣，響應示例也可能是所有可能返回信息的子集。

‌但是，響應模式包含響應中返回的所有可能的屬性。這就是為什麼同時需要一個響應示例和一個響應模式的原因。這是Sunrise和Sunset Times API的響應架構：

模式或模型提供以下內容：

• 每個屬性的描述
• 每個屬性的數據類型的定義
• 每個屬性是必需的還是可選的

如果標頭信息對於包含在響應示例中很重要（因為它提供了標準狀態代碼以外的唯一信息），則也可以包含它。

‌您需要定義響應嗎？

一些API文檔省略了響應模式，因為響應可能看起來不言而喻或直觀。在Twitter的API中，沒有說明響應（您可以在此處查看示例）。

但是，使用描述的響應，大多數文檔會更好，特別是如果屬性是縮寫或含糊的。開發人員有時會通過減少發送的文本量來簡化響應以提高性能。在我記錄的一個端點中，響應包括大約20個不同的兩個字母的縮寫。我花了幾天時間追蹤每個縮寫的含義，發現許多使用該API的開發人員甚至都不知道許多響應的含義。

‌

在示例響應中使用實際值

在示例響應中，值應該是真實的而不是被真實的。如果開發人員給您提供了示例答覆，請確保這些值合理且不會偽造成他們會分散注意力（例如，由漫畫人物名稱組成的用戶）。

此外，樣本響應中不應包含真實的客戶數據。如果您從工程師那裡得到了樣本答覆，並且數據看起來真實，請確保它不僅來自克隆的生產數據庫，而且通常是這樣做的。開發人員可能沒有意識到數據必須是虛構的但具有代表性，因此抓取生產數據庫可能是最簡單的方法。

‌

格式化JSON並使用代碼語法突出顯示

‌對響應使用正確的JSON格式。JSON Formatter和Validator之類的工具可以確保間距正確。

‌如果您還可以添加語法突出顯示，則一定要這樣做。如果您在GitHub上使用靜態網站生成器（例如Jekyll或markdown語法），則可能可以使用Rouge內置語法突出顯示器。其他靜態站點生成器可能使用Pygments或類似的擴展名。

‌Rouge和Pygments依靠“詞法分析器”來指示應如何突出顯示代碼。例如，一些常見的詞法分析器是java，json，html，xml，cpp，dotnet和javascript。

‌如果您沒有任何語法突出顯示工具可以直接集成到創作工具中，則可以使用在線語法突出顯示工具，例如tohtml.com/jScript/。但是，將代碼手動粘貼到這些編輯器中將是乏味的，並且可能是不可持續的。

‌記錄嵌套對象的策略

‌很多時候，響應包含嵌套的對象（對象內的對象）或具有重複元素。格式化響應模式的文檔是API參考文檔更具挑戰性的方面之一。

‌表格是最常用的。在Peter Gruenbaum關於Udemy的API技術寫作課程中，Gruenbaum使用具有不同列的表來表示嵌套對象：

Gruenbaum使用表格主要是為了減少對工具的重視，並將其更多地放在內容上。Dropbox API用斜槓表示嵌套。例如，name_details /，team /和quota_info指示多個對象級別。

‌其他API將嵌套響應定義以模仿JSON結構。這是來自bit.ly API的示例：

多層次的結構通常讓人望而卻步，但在這裡，它的目的是在不需要複雜樣式的情況下很好地工作。

‌eBay的方法更具獨特性。在這種情況下，MinimumAdvertisedPrice嵌套在DiscountPriceInfo內，DiscountPriceInfo嵌套在Item中，Item嵌套在ItemArray中。（另請注意，此響應使用XML而不是JSON）。

以下是響應文檔：

同樣有趣的是，eBay為每個商品包含了多少細節。Twitter的作者似乎省略了描述，而eBay的作者則寫了一些小小說來描述回應中的每個項目。

‌三欄式設計

‌一些API將響應放在右列，因此您可以在查看響應的同時查看資源描述和參數。Stripe的API使這種三列設計廣受歡迎：

Stripe的設計將示例響應並置在右側窗格中，並將響應模式顯示在主窗口中。想法是您可以同時看到兩者。描述不一定總是與響應一致，這可能會造成混淆。不過，將響應示例與響應模式分開放在不同的列中有助於區分兩者。

許多API都按照Stripe的設計建模。例如，請參閱“Slate”或“Spectacle”。您應該在API文檔中使用三列布局嗎？也許。但是，如果響應示例和說明未排成一行，則觀看者的注意力將有所分散，並且用戶必須訴諸於更多的上下滾動。另外，如果您的佈局使用三列，則中間列將有一些狹窄的限制，不會為屏幕截圖和代碼示例留出太多空間。‌

MYOB開發人員中心採用了一種有趣的方法來記錄其API中的JSON。他們以類似於表格的方式列出JSON結構，並具有不同的縮進級別。您可以將鼠標移到工具提示說明的字段上，也可以單擊它以在下面展開說明。使用工具提示可使包含示例和說明的行完美對齊。

JSON定義的右側是帶有實數值的代碼示例。選擇一個值時，表中的元素和代碼示例中的元素都同時突出顯示。

這種方法有助於掃描，而popover +可摺疊方法使您可以壓縮表，從而可以跳到感興趣的部分。但是，從文檔角度來看，這種方法需要更多的手動工作。不過，如果您有很長的JSON對象，那可能是值得的。

嵌入動態響應

‌有時，響應是根據對測試系統的API調用動態生成的。或者，如果不是動態生成的，則它們似乎是動態的。例如，查看OpenWeatherMap API（我們在先前的活動中使用過）。當您單擊“ API調用示例”部分中的鏈接（例如http://samples.openweathermap.org/data/2.5/weather?q=London）時，您會在瀏覽器中看到返回的響應。

‌實際上，OpenWeatherMap響應不是動態生成的，而是以這種方式生成的。

‌對於返回公共信息的GET請求，此動態方法效果很好。但是，它可能無法擴展為其他方法（例如POST或DELETE）或請求授權的方法。

‌

那狀態碼呢？

‌響應部分有時會簡要列出響應返回的可能狀態和錯誤代碼。但是，由於這些代碼通常是在API中的所有端點之間共享的，因此除了特定端點的文檔外，狀態和錯誤代碼通常都記錄在其自己的部分中。因此，我在記錄狀態和錯誤代碼中介紹了此主題。

閱讀更多 沙場點兵見穹蒼 的文章

關鍵字: 跳槽那些事兒 JSON Instagram