API快速參考指南介紹

快速參考指南的功能與入門教程不​​同。儘管入門教程通過提供端到端指令來提出簡單的API請求來幫助初學者定位，但快速參考指南通常通過提供API端點列表來幫助用戶瞭解整個系統。

目錄

• 快速參考指南的需求
• 便於提煉信息
• 快速參考指南示例
• 活動：快速參考指南

快速參考指南的需求

無論是最終用戶文檔還是開發人員文檔，快速參考指南都提供了1至2頁的指南，該指南簡要概述了系統中的核心任務和功能。

快速參考指南將關鍵信息壓縮為簡短格式，以便於使用

快速參考指南應為用戶提供足夠的信息，以使他們瞭解系統的要旨，包括關鍵端點和任務。端點通常與API相互關聯，您可以直觀地描述它們之間的關係。這是我在上一家公司創建的API圖：

快速參考指南格式

出於隱私原因，該文本為拉丁語填充符，因此邏輯可能並不完全清楚。但是使用此API，可以將端點組織為不同的組。一些組在端點內具有多個級別，並且每個端點都有多個包含選項。我在Adobe Illustrator中創建了此圖，並將其作為PDF分發。開發人員發現它很有用，因為它試圖從整體上理解API，顯示出所有端點如何在邏輯上和諧地組合在一起。快速參考指南最常見於API文檔，列出了端點的簡短描述。因此，Swagger UI輸出通常可以用作快速參考指南。

在API文檔之外，快速參考指南往往將重點更多地放在任務上。如果您可以設置或配置服務，則可以採用敘述性而非視覺格式。這是此類指南的示例佈局：

這種快速參考指南格式比API端點更側重於任務

但是，對於API文檔，通常快速參考指南著重於端點的可視分組或顯示，因為這是API的核心功能。

便於快速提煉信息

快速參考中的信息通常不能單一來源，因為它不僅是文檔的摘錄，還是整個系統的簡要介紹。結果，很多時候快速參考文檔就行一個技術作家未完成的半成品。但是為了獲得最佳的用戶體驗，不應跳過快速參考指南，因為它為用戶提供了無法估量的價值。

創建快速參考指南時，請嘗試將最重要的信息壓縮為一兩個頁面，用戶可以將其打印並釘在牆上。“壓縮”並不是說將字體縮小到6點，減少前導並消除所有空白。藉助快速參考指南，您可以掌握一些功能強大且複雜的內容，並以對用戶仍然保持清晰的方式將其精煉為實質。

通過這種提煉，快速參考指南方便用戶瞭解信息。提供系統的高級概述可幫助用戶在深入研究細節之前獲得整體感覺。

將大量信息提取為簡潔明瞭的標題，摘要，標題，微型TOC和主題句子，可以促進信息的消耗和理解。快速參考指南通過將整個系統壓縮成微型系統，將提煉原理提高到了另一個層次。

‌快速參考指南就像技術寫作的詩一樣。目標不僅是簡短或簡潔。詩人通過詩歌試圖喚起一種情緒或畫出一個瞬間，並在那短暫的瞬間捕捉到整體的本質。編寫快速參考指南的工作幾乎相同。這並不是說您只是為了使文檔簡短或為了限制輸出而只用了一些文字，而是試圖將文檔壓縮為一個整體並表達其最低要求。

我同意，利用少量信息描述清楚整個系統，該任務可能是不可能的。儘管如此，這種嘗試還是值得的，其理念仍然不變。快速參考指南教我們每個人如何在5分鐘而不是5小時內使用該系統。這是一種簡化和提高語言效率的理念。

不要被快速參考指南的簡潔和範圍所欺騙。在拼湊佈局，範圍和簡潔性以創建本指南時，您可能需要花費幾天時間才能編寫一頁。但是，完成之後，您實際上可以構圖出結果。

快速參考指南示例

以下是來自各種API文檔站點的示例快速參考指南。

Eventful

Eventful的快速參考指南

Eventful提供了按資源組組織的API中所有端點的一頁快速列表。每個端點大約用半行描述，因此您可以快速瞭解所有端點。例如，快速參考中的/ events / get的描述是“獲取事件記錄”。但是，如果您單擊以獲取更多詳細信息，則更詳細的定義是“給出事件ID，返回與該事件關聯的事件數據。有關示例界面，請參見
http://eventful.com/events/E0-001-000278174-6。”

一眼看到所有端點，您便會有所瞭解。通過從高處俯瞰森林，您可以看到整個森林的形狀。您可能不知道森林包含哪種樹，但是您可以瞭解其他細節，而這些細節在您看一棵樹時並不明顯。

Parse

Parse的快速參考指南

Parse的快速參考與Eventful相似，都有很長的端點列表，只是Parse是按表分組的。請注意，此快速參考頁只是文檔的單個較長頁面中的一部分。按照他們的方法，所有文檔都在同一頁上，但是當您向下滾動時，側欄中的不同條目會突出顯示。有

時，開發人員喜歡單頁方法，因為它減少了信息碎片，並允許他們使用Ctrl + F查找關鍵字的所有實例。我在單頁文檔中研究了這種單頁方法與“點擊瘋狂”的權衡。

如果您在GitHub上使用OpenAPI參考文檔，則會注意到這些文檔也包含在單個頁面中。開發人員可能想使用Ctrl + F快速查看主題的所有實例。但是，我不喜歡這種單頁文檔，因為它為用戶提供了很多視覺上的複雜性。

Shopify

Shopify快速參考指南

Shopify快速參考指南不是針對API的，但是它確實顯示了Liquid（可用於開發人員的一種腳本語言）中的過濾器，變量和其他功能。Shopify在這裡利用摺疊和展開功能來壓縮信息。

該快速參考指南非常方便，因為它使您可以立即瀏覽Liquid中的所有可用功能，因此您可以瞭解要獲取的更多信息。就像液體地形的地圖一樣。該映射使您知道存在的所有功能。

活動：快速參考指南

在您確定的開源項目中，確定有關API快速參考指南的信息。回答以下問題：

1. 該API是否有快速參考指南？也許是API端點的快速列表？
2. 是否有Swagger UI輸出可作為API的快速參考？
3. 如果沒有快速參考指南，API會從中受益嗎？為什麼或者為什麼不？
4. 除了列出端點的簡短描述之外，您還將在API快速參考指南中添加什麼？常見任務？
5. 用戶需要使用API​​執行幾項基本任務？在入門教程中還會傳達這些核心任務嗎？