Swagger入門教程
關於 Swagger
Swagger能成爲最受歡迎的REST APIs文檔生成工具之一，有如下幾個緣由：html
- Swagger 能夠生成一個具備互動性的API控制檯，開發者能夠用來快速學習和嘗試API。
- Swagger 能夠生成客戶端SDK代碼用於各類不一樣的平臺上的實現。
- Swagger 文件能夠在許多不一樣的平臺上從代碼註釋中自動生成。
- Swagger 有一個強大的社區，裏面有許多強悍的貢獻者。
Swagger 文檔提供了一個方法，使咱們能夠用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了好比 names、order 等 API 信息。git
你能夠經過一個文本編輯器來編輯 Swagger 文件，或者你也能夠從你的代碼註釋中自動生成。各類工具均可以使用 Swagger 文件來生成互動的 API 文檔。github
注意：用 Swagger 文件生成互動的 API 文檔是最精簡的，它展現了資源、參數、請求、響應。可是它不會提供你的API如何工做的其餘任何一個細節。web
Petstore 的 Swagger 例子
爲了更好的理解 Swagger ，咱們如今來探索一下 Petsotre 項目的例子。記住：如下出現的 UI 都是指Swagger UI。Swagger 能夠被展現成不一樣的視覺樣式，這取決於你所使用到的視覺框架。數據庫
有三個資源：pet，store，user。apache
建立一個 pet
一、展開 pet 的 post 方法
二、而後單擊 Model Schema 中的黃色字體的 JSON。json
這裏用 JSON 填充了 body value。這裏的 JSON 是你必須上傳的，用於建立 pet 資源。後端
三、將第一個 id 標籤的值修改一下（你必須保證 id 值都是惟一的，而且不能從 0 開始）。api
四、將 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"