Swagger入門教程

来源:http://www.cnblogs.com/JoiT/archive/2017/02/08/6378086.html
-Advertisement-
Play Games

Swagger Web API 文檔 Web API 線上文檔 Web API 手冊 Web API 線上手冊 ...


[譯]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 可以被展示成不同的視覺樣式，這取決於你所使用到的視覺框架。

Petstore UI

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

創建一個 pet

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

pet

這裡用 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 的實現例子

它們大多看起來一樣。你會註意到 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: "[email protected]"
   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


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • 微信紅包實現演算法
    隨著目前微信越來越火，所以研究微信的人也就越來越多，這不前一段時間，我們公司就讓我做一個微信公眾號中問卷調查發紅包功能，經過一段時間的研究，把功能完成，裡面主要的實現步驟都是按照微信公眾號開發文檔來的，很詳細，在整個過程唯有紅包演算法需要仔細編寫，因為畢竟涉及到錢，所以得小心，而且不僅微信中需要發紅包 ...
  • 【Java每日一題】20170210
    20170209問題解析請點擊今日問題下方的“【Java每日一題】20170210”查看（問題解析在公眾號首發，公眾號ID：weknow619） 今日問題： 請問主程式輸出結果是什麼？（點擊以下“【Java每日一題】20170210”查看20170209問題解析） 題目原發佈於公眾號、簡書：【Jav ...
  • FunDA（8）－ Static Source：保證資源使用安全 - Resource Safety
    我們在前面用了許多章節來討論如何把數據從後臺資料庫中搬到記憶體，然後進行逐行操作運算。我們選定的解決方案是把後臺數據轉換成記憶體中的數據流。無論在打開資料庫表或從資料庫讀取數據等環節都涉及到對資料庫表這項資源的安全使用：我們最起碼要保證在完成使用或者使用中途出現錯誤異常退出時能釋放占用的資源。談到資源使 ...
  • python學習筆記（1）
    #!/usr/bin/eny python #! -*- coding:utf-8 -*- """ import time a1 = True while a1: print('1') time.sleep(3) a1 = False print('end') """ #菜比的輸出10內的整數。 #... ...
  • 組合模式（18）
    我們來講一下組合模式： 怎麼是組合模式呢？組合模式，將對象組合成樹形結構以表示‘部分-整體’的層次結構，組合模式是的用戶對單個對象和組合對象的用用具有一致性。 與一個很簡單的例子，公司的組織架構，大都是樹枝結構的。下麵，我們來看一下如何用組合模式寫樹枝結構。 客戶端 結果： 好，是不是很簡單啊…… ...
  • 設計模式學習-外觀模式
    外觀模式 目的：的意圖是為子系統提供一個介面，方便其使用。 外觀模式常用於一些常規的應用程式的開發，因為一般都會對子系統的類進行重構，所以外觀類主要的職責就是為了給子系統提供簡單的訪問方式， 使其有一個明確的目的，從而完成對系統的重構。外觀類介於工具類和應用程式之間。 要註意實例與外觀的區別： 1、 ...
  • haproxy學習——簡介、基本配置（二）
    官網：http://www.haproxy.org/ 個人感覺haproxy學習的重點在於配置上，把配置文檔搞懂了就明白大部分套路了。不過本篇內容屬於入門學習：1.使用haproxy簡單的實現負載均衡的效果。2.使用自帶監控查看效果。後續待學習的方向是訪問日誌配置、優化等~ 簡介： 我在虛擬機上裝的 ...
  • C#_自定義簡單ORM
    一，基本思路：利用C#的標簽和反射功能實現自定義輕量級ORM 標簽Attribute附著在實體屬性或實體類名上，這樣可以取到實體對應的表名，屬性對應的表欄位名，數據類型，是否主鍵，欄位註釋等基本信息 反射實現對實體動態賦值取值。 二，比較重要的類 1、ISqlHelper：介面，定義數據操作的基本方 ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 QuestPDF 是一個開源 .NET 庫，用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫，它徹底改變了我們生成 PDF 文檔的方 ...
  • 彈幕樹洞項目功能新增篇
    項目地址 項目後端地址： https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址： ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址： http://tree ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類