在這門有關編寫REST API文檔的課程中，我不只是在談論抽象概念，而是通過直接的動手方法將REST API關聯起來。首先，您將通過使用簡單的天氣API在站點上放置天氣預報來了解API文檔。

使用API??時，您將了解端點，參數，數據類型，身份驗證，curl，JSON，命令行，Chrome的開發者控制臺，JavaScript等。其思想是，您不必通過獨立于上下文來學習這些概念，而可以通過使用API??來沉浸在真實的場景中來學習它們。浸入實際場景中會使這些工具和技術變得更有意義。

然后，我們將過渡到REST API的標準，工具和規范。您將了解API文檔中的必需部分，分析來自多家公司的REST API文檔的示例，了解如何加入開源項目以獲取經驗，等等。

目錄

• 關于REST API
• 從實踐到文檔
• 該課程適合誰
• 課程組織
• 順序和活動
• 這門課程是否可以幫助您找到API文檔中的工作？
• 無需編程技能
• 您需要什么
• 測試你的設置

關于REST API

簡而言之，REST API(Web API的一種)涉及請求和響應，與訪問網頁不太相似。您對存儲在服務器上的資源進行請求，服務器將以請求的信息進行響應。用于傳輸數據的協議是HTTP。“ REST”代表代表性狀態轉移。

REST API涉及通過HTTP協議的請求和響應

從實踐到文檔

在本課程中，您像開發人員一樣練習使用API??之后，您將轉變觀點并“成為技術作家”，負責記錄工程師添加到API的新端點。作為技術作家，您將解決REST API文檔中參考主題的每個元素：

資源說明

終點和方法

參量

請求示例

回應范例

通過研究這些部分，您將對如何記錄REST API有深入的了解。您還將學習如何記錄API的概念性部分，例如入門指南，狀態和錯誤代碼，請求授權等。

最后，您將深入研究發布REST API文檔的各種方式，探索GitHub，Jekyll等工具和規范以及其他按文檔編碼的方法。您將學習如何利用模板，構建交互式API控制臺，以便用戶可以嘗試請求和查看響應，以及如何通過版本控制來管理您的內容。

我們還將深入研究諸如OpenAPI規范和Swagger UI(為OpenAPI規范提供工具)之類的規范。此外，您還將學習如何記錄本機庫API并生成Javadoc。在整個課程中，我將通過動手練習和演示將這些概念置于真實，適用的環境中。

該課程適合誰

本課程主要服務于以下受眾：

• 尋求從GUI文檔過渡到面向開發人員的更多API集中文檔的專業技術作家。
• 學生將學習如何為在技術通訊領域取得成功而進行技術上的準備，而該領域正越來越側重于開發人員文檔。
• 正在編寫自己的API并希望了解技術文檔的結構，術語和樣式的最佳做法的開發人員。

課程組織

?下面提供了本課程各部分的說明：

• I：REST API簡介：REST API在市場上正在蓬勃發展，并且網絡正在成為互連API的混搭。REST API包括對Web服務器的請求和響應。對于可以編寫開發人員文檔的技術作家來說，工作前景很熱。本課程將幫助您深入了解API文檔，尤其是在完成許多項目組合構建活動時。
• II：像開發人員一樣使用API??：扮演開發人員的角色將有助于您更好地了解開發人員的需求，以及開發人員通常在API文檔中尋找的內容。開發人員經常使用諸如Postman或curl的工具進行呼叫。他們查看響應的結構，并將所需的信息動態集成到網頁和其他應用程序中。
• III：記錄API端點：API端點的參考文檔包括五個常規部分：資源描述，端點和方法，參數，示例請求以及示例響應和模式。要記錄API的參考端點，請為每個部分提供詳細信息。
• IV：OpenAPI規范和Swagger：OpenAPI規范提供了描述REST API的正式方法，并包括上一節“記錄API端點”中提到的所有參考部分。諸如Swagger UI之類的顯示框架可以解析OpenAPI規范并生成交互式文檔，使用戶可以在了解API的同時試用端點。
• V：測試API文檔：測試文檔對于提供準確，全面的信息至關重要。使用API??和開發人員文檔，由于高度的復雜性和工程要求，技術編寫者可能傾向于僅獲取工程師提供給他們的信息并將其批發地合并，而無需親自對其進行測試。但是，僅發揮編輯/發布功能，可以將您的角色減少為工程師的秘書。
• VI：API文檔中的概念性主題：雖然API中的參考主題通常最受關注，但概念性主題(例如入門教程，有關授權的信息，速率限制，狀態和錯誤代碼，快速參考指南以及其他主題)構成了以下主題：文檔的一半。這些主題通常由技術作家而不是工程師處理。您可以通過查看API文檔是否包括這些概念性主題來部分評估API文檔的質量。
• VII：代碼教程：本節介紹創建代碼教程的策略。我仍在開發本節，因此很多內容正在建設中。
• VIII：發布API文檔：API文檔通常遵循以文檔為文檔的工作流程，其中編寫和發布文檔的工具與開發人員用來編寫，管理，構建和部署代碼的工具緊密匹配。Docs-as-code涉及使用Markdown等輕量級格式，通過Git或其他版本控制進行協作，使用靜態站點生成器構建文檔站點，并通過連續構建模型進行部署，在此過程中，當您按入時在服務器上進行構建提交到特定分支。
• IX：在API文檔空間中蒸蒸日上：要獲得API文檔工作并蒸蒸日上，您需要通過撰寫作品集來證明自己的技術才能。產品組合應包括為開發人員編寫的文檔樣本。建立此項目組合的一種方法是通過開發一個開源項目。您還需要居住在可提供API文檔工作的技術中心，例如加利福尼亞，德克薩斯州，紐約或弗吉尼亞州。總體而言，要在開發人員文檔空間中蓬勃發展，您需要不斷學習健康的代碼，這可能是一個挑戰。
• X：本機庫API：本機庫API指Java，C ++或其他特定于編程的API。在此模型中，您無需下載代碼庫并將其集成到您的項目中，而無需通過網絡請求信息。該庫直接編譯到您的應用程序的內部版本中(而不是像REST API一樣通過Web協議進行訪問)。盡管這種類型的API不太常見，但我還是在此處將其部分包括在內，以闡明是什么使REST API與本機庫API如此不同。
• XI：API詞匯表和資源：API文檔范圍充滿術語，首字母縮寫詞和許多新術語。本詞匯表提供了術語和定義的列表。此外，本節還包含其他練習和信息，例如，更多用于調用API的活動或有關替代規范的更多信息。

順序和活動

順序和活動您無需按順序閱讀各個部分，您可以根據需要隨意跳過。但是，前面的某些部分(例如，有關使用REST API(如開發人員和Documenting端點)的部分)在相同的Weather API場景下遵循某種順序。

由于本課程的目的是幫助您學習，因此許多活動需要動手編碼和其他練習。除了學習活動外，還進行了概念上的深入研究，但重點始終是邊做邊學。在有動手活動的地方，我通常在標題部分中添加此圖標：。

其他主題的標題中帶有“活動”一詞。這些活動被集成到各個部分中，但是您還可以在Workshop活動中看到活動的合并子集。這些是我們在現場研討會中進行的活動。

我將這里的內容稱為“課程”，而不是書或網站，主要是因為在每個部分中我都進行了很多練習，而且我發現想要學習API文檔的人們更喜歡動手實踐“當然”的經驗。

這門課程是否可以幫助您找到API文檔中的工作？

人們參加本課程的最常見原因是過渡到API文檔。本課程將幫助您進行過渡，但您不能只是被動地閱讀內容。您需要執行每個部分中概述的活動，尤其是涉及使用開源項目中的內容的主題。這些活動對于建立投資組合的經驗和信譽至關重要。我在“獲取API文檔”和“蓬勃發展”中提供了更多詳細信息。

無需編程技能

至于本課程所需的技術背景，您不需要任何編程背景或其他先決條件，但有助于了解一些基本的HTML，CSS和JavaScript。如果您確實熟悉編程概念，則可以快速瀏覽某些部分，然后跳到您想了解更多的主題。不過，本課程假定您是新手。

本課程中的某些代碼示例使用JavaScript。JavaScript可能是也可能不是您在記錄REST API時實際使用的語言，但是很可能會有一些編程語言或平臺變得很重要。

JavaScript是最熟悉的最有用和最簡單的語言之一，因此，在此REST API文檔介紹的代碼示例中，JavaScript效果很好。JavaScript允許您僅通過在瀏覽器中打開代碼(而不是在IDE中進行編譯)來測試代碼。(如果需要的話，我在這里提供了JavaScript速成課程。)

您需要什么？

您需要使用以下一些工具來完成本課程中的活動：

• 有電源線的筆記本電腦。在進行各種活動時，請確保帶好計算機和充電線。
• 文本編輯器。如果您還沒有收藏的文本編輯器，請下載Sublime Text，它在Mac和Windows上都可以正常運行，并且是免費的。如果您有其他喜歡的文本編輯器(例如，Visual Studio Code，Atom或什至Notepad ++)，也可以使用。只要確保您可以用純文本編寫代碼即可。
• Chrome瀏覽器。Chrome提供了一個Javascript控制臺，可以很好地檢查JSON，因此我們將使用Chrome。另外，為了在瀏覽器中更輕松地讀取JSON響應，請安裝JSON Formatter Chrome擴展程序。
• Postman。Postman是一款應用程序，可讓您通過GUI客戶端發出請求并查看響應。確保您下載的是應用程序，而不是Chrome擴展程序。
• curl。curl對于從命令行向端點發出請求至關重要。Mac已經內置了curl，但默認情況下Windows上可能不提供它。(某些Windows 10內部版本已在Powershell中使用它。)在Windows上，打開命令提示符并鍵入curl -V。如果尚未安裝，請訪問confusedbycode.com/curl并安裝一個版本(通常是“具有管理員權限(免費)，64位”)。關閉并重新打開命令提示符，然后嘗試再次鍵入curl -V。
• Git。Git是開發人員經常用于在代碼上進行協作的版本控制工具。對于Windows，請參閱https://gitforwindows.org/來設置Git和Git BASH終端仿真器。對于Mac，請參閱下載Git。
• GitHub帳戶。GitHub將用于各種活動，有時會演示Git工作流，而有時會用作開發人員工具的身份驗證服務。如果您還沒有GitHub帳戶，請注冊一個。
• Stoplight Studio編輯器。在使用OpenAPI規范時，我們將使用Stoplight Studio編輯器。Stoplight Studio提供了可視化建模工具，可用于OpenAPI規范。Stoplight提供了該瀏覽器的Web瀏覽器版本和獨立的應用程序版本。我們將使用網絡瀏覽器版本，因為它提供了更完整的功能(例如嘗試請求)。轉到https://stoplight.io/p/studio并使用Gi??tHub登錄。
• OpenWeatherMap API密鑰。我們將使用OpenWeatherMap API進行一些練習。OpenWeatherMap API密鑰需要花費幾個小時才能生效，因此最好提前獲取API密鑰-然后，當您進入OpenWeatherMap API活動時，一切都會準備就緒。要獲取(免費的)OpenWeatherMap API密鑰，請訪問https://openweathermap.org/。點擊頂部導航欄中的注冊并創建一個帳戶。注冊后，OpenWeatherMap將API密鑰發送給您的電子郵件。您也可以在登錄并在信息中心中單擊“ API密鑰”選項卡時找到它。將密鑰復制到可以輕松找到的位置。

測試您的設置

過去，人們要求進行一些測試以檢查筆記本電腦的設置是否正確。

• 如果要測試Postman是否工作，請打開Postman應用程序并將其粘貼到GET框中：https://api.openweathermap.org/data/2.5/weather?zip=95050&units=imperial&appid=126cac1a482f51de0f1287b45ae2bf9a。
• 然后單擊發送。如果您收到回復，則說明該回復正常。(在極少數情況下，有時人們會對計算機進行安全限制，以阻止所有網絡訪問。)如果要測試是否安裝了curl，請打開Terminal(在Mac上)或Command Prompt(在Windows上)，然后粘貼curl -X GET“ https://api.openweathermap.org/data/2.5/weather?zip=95050&units= imperial＆appid = 126cac1a482f51de0f1287b45ae2bf9a”。如果收到JSON響應，那就很好。
• 要檢查是否已安裝Git，請打開Terminal(在Mac上)或Command Prompt(在Windows上)，然后鍵入git --version。如果已安裝，則會看到該版本。

本文章翻譯來源自海外課程

總結

以上是生活随笔為你收集整理的api如何使用_记录API：技术作家和工程师指南的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。