Swagger入門教程(轉)

[譯]5.41 Swagger tutorial

單擊此處查看原文

更多概念參見：Implementing Swagger with your API docs

關於 Swagger

Swagger能成為最受歡迎的REST APIs文檔生成工具之一，有以下幾個原因：

• Swagger 可以生成一個具有互動性的API控制台，開發者可以用來快速學習和嘗試API。
• Swagger 可以生成客戶端SDK代碼用於各種不同的平台上的實現。
• Swagger 文件可以在許多不同的平台上從代碼注釋中自動生成。
• Swagger 有一個強大的社區，里面有許多強悍的貢獻者。

Swagger 文檔提供了一個方法，使我們可以用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了比如 names、order 等 API 信息。

你可以通過一個文本編輯器來編輯 Swagger 文件，或者你也可以從你的代碼注釋中自動生成。各種工具都可以使用 Swagger 文件來生成互動的 API 文檔。

注意：用 Swagger 文件生成互動的 API 文檔是最精簡的，它展示了資源、參數、請求、響應。但是它不會提供你的API如何工作的其他任何一個細節。

Petstore 的 Swagger 例子

為了更好的理解 Swagger ，我們現在來探索一下 Petsotre 項目的例子。記住：以下出現的 UI 都是指Swagger UI。Swagger 可以被展示成不同的視覺樣式，這取決於你所使用到的視覺框架。

有三個資源：pet，store，user。

創建一個 pet

1、展開 pet 的 post 方法
2、然后單擊 Model Schema 中的黃色字體的 JSON。

這里用 JSON 填充了 body value。這里的 JSON 是你必須上傳的，用於創建 pet 資源。

3、將第一個 id 標簽的值修改一下（你必須保證 id 值都是唯一的，並且不能從 0 開始）。

4、將 name 標簽的值修改一下（最好也要唯一，方便對比結果），以下是示例代碼：

{ "id": 37987, "category": { "id": 0, "name": "string" }, "name": "Mr. Fluffernutter", "photoUrls": [ "string" ], "tags": [ { "id": 0, "name": "string" } ], "status": "available" }

5、單擊 Try it out! 按鈕，查看響應：

通過 ID 查詢 pet

展開 Get 方法：pet/{petId}，輸入你的 petId，單擊 Try it out!，你創建的 pet 就會顯示在 response 中。
默認情況下，api 響應都是 xml。可以把 Response Content Type 修改為 application/json 再試一次。
返回的值將會是 JSON 格式

注意：值得強調的是 Swagger 文檔一定要通過着手嘗試來學習。你要通過實實在在的發送請求和查看響應來更好的理解 Petstore API 是如何工作的。但是還要注意現在你已經在你的真實Petstore數據庫中創建了一個新的pet。從學習嘗試 API 過渡到在生產環境中使用 API 的時候，那些測試數據你可能都需要將它們刪除。

整理 Swagger 組件

Swagger 分成一些不同的塊。

Swagger spec：這一塊對元素的嵌套、命令等采用官方模式。如果你想要對 Swagger 文件手動編碼，你必須非常熟悉 Swagger spec。

Swagger editor：這是在線編輯器，用於驗證你的 YML 格式的內容是否違反 Swagger spec 。YML 是一種句法，依賴於空格和嵌套。你需要對 YML 句法很熟悉才能很好的遵守 Swagger spec 規范。Swagger 編輯器會標出錯誤並且給你格式提醒（Swagger spec 文件可以使用 JSON 或者 YAML 中的任意一種格式）。

Swagger-UI：這是一套 HTML/CSS/JS 框架用於解析遵守 Swagger spec 的 JSON 或 YML 文件，並且生成API文檔的UI導航。它可以將你的規格文檔轉換成Swagger Petsotre-like UI。

Swagger-codegen：這個工具可以為不同的平台生成客戶端 SDK（比如 Java、JavaScript、Python 等）。這些客戶端代碼幫助開發者在一個規范平台中整合 API ，並且提供了更多健壯的實現，可能包含了多尺度、線程，和其他重要的代碼。SDK 是用於支持開發者使用 REST API 的工具。

一些 Swagger 的實現例子

• Reverb
• VocaDB
• Watson Developer Cloud

它們大多看起來一樣。你會注意到 Swagger 實現的文檔都很精簡。這是因為 Swagger 的展示都是互動的體驗，你可以嘗試請求和查看響應，使用你自己的 API 密鑰來查看你自己的數據。它是邊看邊做邊學的形式。

它也有一些缺陷：

• 沒有太多的空間來描述后端詳細的工作
• 每個 Swagger UI 的輸出看起來都差不多
• Swagger UI 會從你其他的文檔中分離成獨立的一個站點

創建 Swagger UI 展示

本節我們將為使用Mashape Weather API的 weatherdata 后台來創建一個 Swagger UI （weatherdata是之前的課程中創建的一個項目）。你可以在這里查看demo。

a.創建一個 Swagger spec 文件

1、去Swagger online editor
2、選擇 File > Open Example 然后選擇 PetStore Simple 。單擊 Open。

你可以使用 weatherdata 后台文檔來自定義這個示例 YML 文件。但如果你是新手， 它會帶你認識spec。方便起見，只需要用到下面的文件，然后復制一份到 Swagger editor: swagger.yaml。

swagger: "2.0" info: version: "1.0.0" title: "Weather API" description: "A sample API that uses a Mashape weather API as an example to demonstrate features in the swagger-2.0 specification" termsOfService: "http://helloreverb.com/terms/" contact: name: "Tom Johnson" email: "[e-mail]" url: "http://swagger.io" license: name: "MIT" url: "http://opensource.org/licenses/MIT" host: "simple-weather.p.mashape.com" schemes: - "https" consumes: - "application/json" produces: - "application/text" paths: /aqi: get: tags: - "Air Quality" description: "gets air quality index" operationId: "getAqi" produces: - "text" parameters: - name: "lat" in: "query" description: "latitude" required: false type: "string" - name: "lng" in: "query" description: "longitude" required: false type: "string" responses: 200: description: "aqi response" default: description: "unexpected error" /weather: get: tags: - "Weather Forecast" description: "gets weather forecast in short label" operationId: "getWeather" produces: - "text" parameters: - name: "lat" in: "query" description: "latitude" required: false type: "string" - name: "lng" in: "query" description: "longitude" required: false type: "string" responses: 200: description: "weather response" default: description: "unexpected error" /weatherdata: get: tags: - "Full Weather Data" description: "Get weather forecast by Latitude and Longitude" operationId: "getWeatherData" produces: - "application/json" parameters: - name: "lat" in: "query" description: "latitude" required: false type: "string" - name: "lng" in: "query" description: "longitude" required: false type: "string" responses: 200: description: "weatherdata response" default: description: "unexpected error" securityDefinitions: internalApiKey: type: apiKey in: header name: X-Mashape-Key

注意：使用 YML 替換JSON。 YML 句法比 JSON 可讀性高。使用 YML ，空格很重要。新段落需要縮進兩個空格。冒號表示個對象。連字符代表一個 sequence 或者 list （像一個 array）。如果你下載這個文件而不是復制粘貼，你基本不會碰到空格問題。

Swagger editor 告訴你文件如何被輸出，你也可以看到驗證出來的錯誤。沒有這個在線編輯器，你只能在運行代碼的時候才能知道 YML 句法是否有效 （並且看到錯誤提示， YAML 文件也不能被正確解析）。

3、保證 Swagger edirot 中的 YAML 文件有效。如果有錯誤必須要修正。

4、選擇 File > Download YAML 並且保存為 swagger.yaml 到本地（你可以只復制代碼然后粘貼到空白文件中，命名為 swagger.yaml）。

你也可以選擇 JSON 格式，不過 YAML 可讀性更高。

b.設置 Swagger UI

1、Github: Swagger UI。下載、解壓。只需要用到 dist 文件夾。除非你想重新生成 dist 中的文件，才會用到別的。

2、打開 dist > index.html

3、找到：url = "http://petstore.swagger.io/v2/swagger.json";

4、值改成 swagger.yaml 的路徑

5、保存打開index.html

c.上傳文件到 web 主機

除了本地瀏覽 Swagger 文件，你也可以使用 XAMPP 在本地運行一個 web 服務器

1、下載安裝XAMPP

2、在你的應用程序文件夾中打開 XAMPP 文件夾，啟動 manager-osx 控制台

3、單擊 Manage Servers tab

4、選擇 Apache Web Server 單擊 Start

5、打開 XAMPP 中的 htdocs 文件夾。如果是Mac，通常在 /Applications/XAMPP/xamppfiles/htdocs。

6、將 dist 文件夾拖到此處

7、在你的瀏覽器中瀏覽 localhost/dist

就可以看到 Swagger UI的展示。

體驗 Swagger UI

1、用瀏覽器瀏覽 Swagger UI。
2、在右上角，單擊 Authorize 並且輸入你的 Mashape API Key。如果你沒有 Mashape API Key，你可以3、使用 EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p。
4、去 Google Maps 搜索一個地址。
5、從 URL 中去獲取經緯度，將其插入到你的 Swagger UI中（比如：1.3319164 for lat, 103.7231246 for lng）
6、單擊 Try it out。

如果成功，你應該可以看到 response body 的響應：9 c, Mostly Cloudy at South West, Singapore

如果你看到了Not supported，嘗試調整經緯度。

如果你刷新了界面，你要重新輸入 API Key。

從注釋中自動生成 Swagger 文件

為了代替 Swagger file 的手動編碼，你也可以從你的程序代碼注釋中自動生成。有許多的 Swagger 庫可以用來整合不同的代碼庫。這些 Swagger 庫可以解析注釋並且生成跟之前手動生成相同的 Swagger 文件。

要整合 Swagger 到自己的代碼中，要允許開發者便捷的撰寫文檔，保證新特性都會被記錄，並且保持文檔的更新。這里是一個教程，使用 Swagger 為 Scalatra 從注釋中自動生成文檔.這些注釋方法根據不同的語言分成不同的 Swagger 文檔塊。

其他工具參見 Swagger services and tools