[譯]5.41 Swagger tutorial
單擊此處查看原文
更多概念參見：Implementing Swagger with your API docshtml
關於 Swagger
Swagger能成爲最受歡迎的REST APIs文檔生成工具之一，有如下幾個緣由：git
- Swagger 能夠生成一個具備互動性的API控制檯，開發者能夠用來快速學習和嘗試API。
- Swagger 能夠生成客戶端SDK代碼用於各類不一樣的平臺上的實現。
- Swagger 文件能夠在許多不一樣的平臺上從代碼註釋中自動生成。
- Swagger 有一個強大的社區，裏面有許多強悍的貢獻者。
Swagger 文檔提供了一個方法，使咱們能夠用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了好比 names、order 等 API 信息。github
你能夠經過一個文本編輯器來編輯 Swagger 文件，或者你也能夠從你的代碼註釋中自動生成。各類工具均可以使用 Swagger 文件來生成互動的 API 文檔。web
注意：用 Swagger 文件生成互動的 API 文檔是最精簡的，它展現了資源、參數、請求、響應。可是它不會提供你的API如何工做的其餘任何一個細節。數據庫
Petstore 的 Swagger 例子
爲了更好的理解 Swagger ，咱們如今來探索一下 Petsotre 項目的例子。記住：如下出現的 UI 都是指Swagger UI。Swagger 能夠被展現成不一樣的視覺樣式，這取決於你所使用到的視覺框架。apache
有三個資源：pet，store，user。json
建立一個 pet
一、展開 pet 的 post 方法
二、而後單擊 Model Schema 中的黃色字體的 JSON。後端
這裏用 JSON 填充了 body value。這裏的 JSON 是你必須上傳的，用於建立 pet 資源。api
三、將第一個 id 標籤的值修改一下（你必須保證 id 值都是惟一的，而且不能從 0 開始）。瀏覽器
四、將 name 標籤的值修改一下（最好也要惟一，方便對比結果），如下是示例代碼：
{
"id": 37987, "category": { "id": 0, "name": "string" }, "name": "Mr. Fluffernutter", "photoUrls": [ "string" ], "tags": [ { "id": 0, "name": "string" } ], "status": "available" }
五、單擊 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 的實現例子
它們大多看起來同樣。你會注意到 Swagger 實現的文檔都很精簡。這是由於 Swagger 的展現都是互動的體驗，你能夠嘗試請求和查看響應，使用你本身的 API 密鑰來查看你本身的數據。它是邊看邊作邊學的形式。
它也有一些缺陷：
- 沒有太多的空間來描述後端詳細的工做
- 每一個 Swagger UI 的輸出看起來都差很少
- Swagger UI 會從你其餘的文檔中分離成獨立的一個站點
建立 Swagger UI 展現
本節咱們將爲使用Mashape Weather API的 weatherdata 後臺來建立一個 Swagger UI （weatherdata是以前的課程中建立的一個項目）。你能夠在這裏查看demo。
a.建立一個 Swagger spec 文件
一、去Swagger online editor
二、選擇 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: "tomjohnson1492@gmail.com" 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 文件也不能被正確解析）。
三、保證 Swagger edirot 中的 YAML 文件有效。若是有錯誤必需要修正。
四、選擇 File > Download YAML 而且保存爲 swagger.yaml 到本地（你能夠只複製代碼而後粘貼到空白文件中，命名爲 swagger.yaml）。
你也能夠選擇 JSON 格式，不過 YAML 可讀性更高。
b.設置 Swagger UI
一、Github: Swagger UI。下載、解壓。只須要用到 dist 文件夾。除非你想從新生成 dist 中的文件，纔會用到別的。
二、打開 dist > index.html
三、找到：url = "http://petstore.swagger.io/v2/swagger.json";
四、值改爲 swagger.yaml 的路徑
五、保存打開index.html
c.上傳文件到 web 主機
除了本地瀏覽 Swagger 文件，你也可使用 XAMPP 在本地運行一個 web 服務器
一、下載安裝XAMPP
二、在你的應用程序文件夾中打開 XAMPP 文件夾，啓動 manager-osx 控制檯
三、單擊 Manage Servers tab
四、選擇 Apache Web Server 單擊 Start
五、打開 XAMPP 中的 htdocs 文件夾。若是是Mac，一般在 /Applications/XAMPP/xamppfiles/htdocs。
六、將 dist 文件夾拖到此處
七、在你的瀏覽器中瀏覽 localhost/dist
就能夠看到 Swagger UI的展現。
體驗 Swagger UI
一、用瀏覽器瀏覽 Swagger UI。
二、在右上角，單擊 Authorize 而且輸入你的 Mashape API Key。若是你沒有 Mashape API Key，你能夠三、使用 EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p。
四、去 Google Maps 搜索一個地址。
五、從 URL 中去獲取經緯度，將其插入到你的 Swagger UI中（好比：1.3319164 for lat, 103.7231246 for lng）
六、單擊 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