swagger editor使用總結

1.使用界面預覽：

 

2.安裝教程：

先到git下載：https://github.com/swagger-api/swagger-editor;

然后直接打開index.html 或者如上圖創建一個服務器，訪問該項目；然后就可以看到如1中的效果了。

具體使用教程可以參考3.

3.使用教程：

Swagger是一種Rest API的 簡單但強大的表示方式，標准的，語言無關，這種 表示方式不但人可讀，而且機器可讀。 可以作為Rest API的交互式文檔，也可以作為Rest API的形式化的接口描述，生成客戶端和服務端的代碼。 

本文介紹Swagger以下內容：

1. Swagger API Spec，描述Rest API的語言
2. Swagger UI，將Swagger API Spec以HTML頁面展現出來的模塊
3. Swagger Editor，Swagger API Spec的編輯器

 

Swagger API Spec/Open API Spec

Swagger API Spec是Swagger用來描述Rest API的語言，類似於描述Web服務的WSDL。Swagger API可以使用yaml或json來表示。 2016年1月，Swagger將Spec捐獻給Open API Initiative (OAI)，成為Open API Spec的基礎。

Swagger API Spec包含以下部分：

• swagger，指定swagger spec版本，2.0
• info，提供API的元數據
• tags，補充的元數據，在swagger ui中，用於作為api的分組標簽
• host，主機，如果沒有提供，則使用文檔所在的host
• basePath，相對於host的路徑
• schemes，API的傳輸協議，http，https，ws，wss
• consumes，API可以消費的MIME類型列表
• produces，API產生的MIME類型列表
• paths，API的路徑，以及每個路徑的HTTP方法，一個路徑加上一個HTTP方法構成了一個操作。每個操作都有以下內容：
• tags，操作的標簽
• summary，短摘要
• description，描述
• externalDocs，外部文檔
• operationId，標識操作的唯一字符串
• consumes，MIME類型列表
• produces，MIME類型列表
• parameters，參數列表
• responses，應答狀態碼和對於的消息的Schema
• schemes，傳輸協議
• deprecated，不推薦使用
• security，安全
• definitions，定義API消費或生產的數據類型，使用json-schema描述，操作的parameter和response部分可以通過引用的方式使用definitions部分定義的schema
• parameters，多個操作共用的參數
• responses，多個操作共用的響應
• securityDefinitions，安全scheme定義
• security，安全聲明
• externalDocs，附加的外部文檔

下面是一個操作的描述

  /pets/findByTags: get: tags: - pet summary: Finds Pets by tags description: Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing. operationId: findPetsByTags produces: - application/json - application/xml parameters: - in: query name: tags description: Tags to filter by required: false type: array items: type: string collectionFormat: multi responses: "200": description: successful operation schema: type: array items: $ref: "#/definitions/Pet" "400": description: Invalid tag value security: - petstore_auth: - write_pets - read_pets 

參數的描述包括：

• name，名字

• description，描述required，是否必須
• in，位置
• Path
• • Query
  • Header
  • Body
  • Form

• （對於Body類型的參數）
• schema，數據類型，可以詳細描述，也可以引用definition部分定義的schema

• （對於Body類型以外的參數）
• type，類型
• format，數據格式
• allowEmptyValue，是否允許空值
• items，對於Array類型
• collectionFormat，對於Array類型
• default，缺省值

Swagger API Spec對你Rest API的每一個操作的請求消息的參數（Path,Query,Body,Form），響應消息的狀態碼和消息體的json結構都進行了詳細的描述。不僅可以供給使用API的開發者學習，而且是對Rest API接口的形式化的抽象。

我們完全可以把Swagger API Spec當作一個API接口的設計語言，就像CORBA IDL或Web服務的WDL一樣，先定義Rest API的操作參數和應答消息，再着手實現這些Rest API，這對Rest API日后的維護也提供了一個設計文檔。

Swagger UI

Swagger UI是Swagger中用於顯示Rest接口文檔的項目，項目由一組HTML，JavaScript和CSS組成，沒有外部依賴。Swagger UI可以根據Swagger Spec的json動態生成漂亮的幫助文檔。支持常見瀏覽器。

Swagger UI如下圖所示：

可以訪問在線Swagger UI：http://petstore.swagger.io/

使用Swagger UI很容易，只要把github項目（https://github.com/swagger-api/swagger-ui）下載到本地:

git clone https://github.com/swagger-api/swagger-ui.git

 

然后用瀏覽器打開dist/index.html就可以。當然也可以放到HTTP Server下通過HTTP協議訪問。

在瀏覽器地址欄中，可以在index.html后添加url參數，就可以自動打開指定的Rest APi的json描述。如：file:///E://swagger-ui/dist/index.html?url=http://petstore.swagger.io/v2/swagger.json

通過編輯index.html，就可以對Swagger UI進行定制，包括：

1. 中文顯示

在html header中添加下面的文字。

<script src='lang/translator.js' type='text/javascript'></script> <script src='lang/zh-cn.js' type='text/javascript'></script> 

中文翻譯位於/lang/zh-cn.js文件，如果有什么不合適的翻譯，可以直接修改。

2. 指定Swagger UI的表現方式

比如：

1. docExpansion：指定操作的描述是收起的還是展開的
2. supportedSubmitMethods：允許哪些HTTP方法的文檔帶Try It!的按鈕
3. operationsSorter：指定操作安裝什么排序

更多請參考官網的文檔。

Swagger Editor

顧名思義，Swagger Editor是Swagger API Spec的編輯器，Swagger API Spec有2中格式，yaml和json，Swagger Editor使用yaml進行編輯，但允許導入和下載兩種格式的文件。在yaml編輯器的右面有所見即所得的預覽。

Swagger Editor的Live Demo：Swagger Editor

Swagger Editor的安裝也很方便，

下載最新的發布版：https://github.com/swagger-api/swagger-editor/releases/download/v2.10.1/swagger-editor.zip

然后解壓到文件夾，用HTTP Server將靜態文件加載起來，下面是安裝node.js的http server並跑起來的指令

npm install -g http-server
wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.1/swagger-editor.zip
unzip swagger-editor.zip
http-server -p 8080 swagger-editor 

http server啟動后，就可以在瀏覽器中輸入地址進行編輯了。

文件菜單提供了主要的功能

• New，創建新的文件
• Open Example，打開內建Swagger API Spec的示例
• Paste Json，將剪貼板的內容貼到編輯器中，取代當前的內容。在Paste之前一定要先下載編輯中的內容
• Import URL/Import File，導入已有的Swagger API Spec，可以是yaml或json格式的
• Download YAML/Download JSON，將編輯的結果下載到本地。

代碼生成

Swagger支持根據Swagger API Spec生成客戶端和服務端的代碼，支持很多語言和框架。這部分我還沒有深入使用。

4.demo：

通過Swagger對於上述的接口編寫文檔，示例如下:

#必要字段！Swagger規范版本，必須填2.0，否則該YAML將不能用於Swagger其他組件 swagger: '2.0' #必要字段！描述API接口信息的元數據 info: #接口標題 title: swagger說明文檔　 #接口文檔的描述 description: 學習Swagger #版本號 version: 1.0.0 #Swagger會提供測試用例，host指定測試時的主機名，如果沒有指定就是當前主機,可以指定端口． host: 127.0.0.1 #定義的api的前綴，必須已/開頭,測試用例的主機則為:host＋bashPath basePath: /api #指定調用接口的協議，必須是:"http", "https", "ws", "wss"．默認是http.-表示是個數組元素，即schemes接受一個數組參數 schemes: - http - https #對應與http協議頭request的Accept，調用者可接受類型,默認是*/*,定義的類型必須是http協議定義的 Mime Types,RestfulAPI一般定義成application/json #這兩個是對所有接口的全局設置，在細化的接口中是還可以對應這兩個屬性來覆蓋全局屬性 produces: - application/json #必要字段!定義可有可操作的API paths: /users: #必要字段!定義HTTP操作方法，必須是http協議定義的方法 get: #接口概要 summary: 查詢所有用戶信息 #接口描述 description: 查詢出所有用戶的所有信息，用戶名，別名 #標簽，方便快速過濾出User相關的接口 tags: - User #返回值描述，必要自動 responses: #返回的http狀態碼 200: description: 所有用戶信息或者用戶的集合信息 #描述返回值 schema: #返回值格式，可選的有array,integer,string,boolean type: array #針對array,每個條目的格式,type定義為array．必要填寫items items: #引用在definitions下定義的Users $ref: '#/definitions/User' #執行出錯的處理 default: description: 操作異常,執行失敗.返回信息描述錯誤詳情 schema: #值類型 type: object #定義屬性 properties: #屬性名 message: #類型 type: string #即對於同一個url定義兩個不同的方法，表示兩個接口 post: description: 注冊一個用戶 #請求參數 parameters: #參數key - name: username #傳遞方法，formData表示表單傳輸，還有query表示url拼接傳輸，path表示作為url的一部分 #body表示http頭承載參數(body只能有一個,有body不能在有其他的) in: formData #參數描述 description: 用戶名，不能使用已經被注冊過的 #參數是否必要，默認false required: true #參數類型，可選的包括array,integer,boolean,string.使用array必須使用items type: string - name: password in: formData description: 用戶登陸密碼，加密傳輸，加密存儲 required: true type: string - name: alias in: formData type: string description: 用戶別名 #非必要字段 required: false responses: #返回的http狀態碼 200: description: 通過返回值來標示執行結果　返回true表示執行成功 schema: #值類型 type: object #定義屬性 properties: #屬性名 status: #類型 type: boolean #描述 description: 是否成功 #執行出錯的處理 default: description: 操作異常,執行失敗.返回信息描述錯誤詳情 schema: #值類型 type: object #定義屬性 properties: #屬性名 message: #類型 type: string /users/{id}: #{id}表示id為請求參數，例如/users/1,/users/2都是對該API的請求，此時id即為１和2 get: summary: 根據用戶名id查詢該用戶的所有信息 description: 查詢出某個用戶的所有信息，用戶名，別名等 tags: - User parameters: #上面接口中定義了{id}，則參數列表中必須包含參數id,並且請求類型為path - name: id in: path description: 要查詢的用戶的用戶名,它是唯一標識 required: true type: string responses: 200: description: 所有用戶信息或者用戶的集合信息 schema: $ref: '#/definitions/User' default: description: 操作異常,執行失敗.返回信息描述錯誤詳情 schema: #值類型 type: object #定義屬性 properties: #屬性名 message: #類型 type: string #http定義的delete方法,刪除一個資源 delete: summary: 刪除用戶 description: 刪除某個用戶的信息，被刪除的用戶將無法登陸 parameters: - name: id in: path type: string required: true description: 用戶的唯一標示符 tags: - User responses: 200: description: 通過返回值來標示執行結果　返回true表示執行成功 schema: #值類型 type: object #定義屬性 properties: #屬性名 status: #類型 type: boolean #描述 description: 是否成功 default: description: 操作異常,執行失敗.返回信息描述錯誤詳情 schema: #值類型 type: object #定義屬性 properties: #屬性名 message: #類型 type: string #描述錯誤信息 #http定義的patch方法，表示修改一個資源 patch: summary: 用戶信息修改 description: 修改用戶信息(用戶名別名) parameters: - name: id in: path description: 用戶名,要修改的數據的唯一標識符 required: true type: string - name: alias in: formData description: 新的用戶別名 required: true type: string tags: - User responses: 200: description: 通過返回值來標示執行結果　返回true表示執行成功 schema: #值類型 type: object #定義屬性 properties: #屬性名 status: #類型 type: boolean #描述 description: 是否成功 default: description: 操作異常,執行失敗.返回信息描述錯誤詳情 schema: #值類型 type: object #定義屬性 properties: #屬性名 message: #類型 type: string #描述錯誤信息 definitions: User: #值類型 type: object #定義屬性 properties: #屬性名 id: #類型 type: string #描述 description: 用戶的唯一id username: type: string description: 用戶名 alias: type: string description: 別名