• Swagger Editor: Swagger提供的一個編輯器，用來通過Swagger提供的特定的YAML語法來編寫API文件
• Swagger Codegen: 程式碼生成器
• Swagger UI: YAML語法定義我們的RESTful API，然後它會自動生成一篇排版優美的API文件，並且提供實時預覽。

我們只需要安裝Swagger Editor就足夠了，它基本上集成了其餘兩個工具
Swagger Editor通過遠端伺服器(http://editor.swagger.io)也可以使用,但速度較慢，我們在本機安裝。

Swagger Editor的安裝:

首先確保你的電腦安裝了NodeJs環境。

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

執行成功後通過本機IP即可使用Swagger Editor,比通過Swagger伺服器快的多。

在Swagger Editor中定義API

通過Swagger提供的特定的YAML語法來定義API,可以詳細的描述API的方法,功能，引數，返回值等資訊。現在通過一個簡單的示例，學習編寫Swagger的YAML文件以及生成服務端程式碼。

通過Swagger定義登陸，註冊，修改，刪除四個RestFul介面:

• 查詢所有的User => /users　　　　　　　　　　　使用get方法
• 新增User => /users 　　　　　　　　　　　　　　　 使用post方法
• 根據某個id查詢對應的User => /users/{id}　　　　　{id}指定了你要查詢的那個id,使用get方法
• 根據某個id刪除對應的User => /users/{id}　　　　　{id}指定了要刪除的那個id,使用delete方法
• 修改某個id對應的User => /users/{id} 　　　　　　　{id}指定了要修改的那個id,使用patch方法
  一個完整的，可閱讀的Swagger YAML的格式層次關係定義如下:

swagger:
info:
  title:
  description:
  version:
host: 
basePath:
schemes:
produces:
paths:
  /users:
    get:
      summary:
      description:
      tags:
      responses:
        httpResponseCode:
          description:
          schema:
        ...#與httpResponseCode同級，可描述多個狀態嗎
    post: 
      summary:
      description:
      tags:
      responses:
        httpResponseCode:
          description:
          schema:
        ...#與httpResponseCode同級，可描述多個狀態嗎

 　　...#與httpMethod同級，對於同一個URL可定義多個方法，表示不同的介面
  /users/{id}:
    delete:
      summary:
      description:
      tags:
      responses:
        httpResponseCode:
          description:
          schema:
        ...#與httpResponseCode同級，可描述多個狀態嗎
    patch:
      summary:
      description:
      tags:
      responses:
        httpResponseCode:
          description:
          schema:
        ...#與httpResponseCode同級，可描述多個狀態嗎 　

假設資料庫中存在一個User表,表字段為_id,username,password,alias。對該表定義出CURD操作介面

通過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: 別名

生成程式碼

　以Spring為例子:
　 點選Swagger Editor上方的generate server，點選Spring。則會根據該API描述生成一套基於Maven構建的Spring-Boot專案，通過安裝相關依賴，執行mvn spring-boot:run則成功執行專案，相關的介面均可進行測試。但這個mock server對於介面並沒有返回值，如果需要一個完整的mock server還需要在此基礎上使用其他工具整合。