Swagger入門教程

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生成客戶端和服務端的代碼，支持很多語言和框架。這部分我還沒有深入使用。

參考文檔

• GitHub - swagger-api/swagger-ui: Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
  
• GitHub - swagger-api/swagger-editor: Swagger Editor
  
• GitHub - swagger-api/swagger-codegen: swagger-codegen contains a template-driven engine to generate client code in different languages by parsing your Swagger Resource Declaration.
  
• OpenAPI-Specification/2.0.md at master · OAI/OpenAPI-Specification · GitHub
  
• JSON Schema - Documentation
  
• http://petstore.swagger.io/v2/swagger.json，Swagger API Spec的官方示例