Swagger Edit 安裝和使用教程

Swagger Edit介紹
Swagger是專門用來管理接口一個工具。在開發過程中,接口一直是紛爭的聚焦點,能有效管理接口(保存好記錄、及時更新、方便查看、接口測試)。會讓整個項目開發效率提升很大。
而其中Swagger Edit是用來編輯接口文檔的小程序,簡單易用。在官網上分爲在線編輯和下載代碼線下編輯,兩種編輯方式。Swagger是通過YAML來定義你的接口規範。可以通過接口文檔幫你生成不同框架的服務端和客戶端,方便你mock和契約測試。最後導出JSON格式的API規範,通過Swagger UI對外發布。下圖就是Swagger Edit界面:
Swagger Edit界面

安裝步驟:
1.下載並且安裝node.js
2. npm install -g http-server
3. 下載項目https://github.com/swagger-api/swagger-editor 並且解壓。
4. 設置HS_HOME,它的值等於hs.cmd的全路徑,並把HS_HOME加入PATH環境變量中
5. 進入swagger-editor文件夾。運行hs -p 400
6. 進入http://127.0.0.1:400 就可以看到swagger頁面了。

界面介紹
swagger edit界面分爲導航欄和工作區。導航欄是對接口文檔的處理用,下面會介紹到。
工作區就是我們花時間最多的地方。分爲左右區域,左邊是編輯區,右邊是顯示區。左邊編輯區使用的YAML語法來編寫,只要一修改右邊顯示區立刻有變化,使用很便捷。進入swagger edit會默認填入一個demo文檔,通常我們只需要修改demo文檔,就能製作我們想要的接口文檔。如下圖:
Swagger Edit界面說明
編寫完文檔點擊展示區的excute,進行測試接口。如下圖
接口測試
ps:Swagger Edit修改會後會立即把數據保存到瀏覽器Local Storage裏面,所以不用擔心關閉瀏覽器就會把數據丟失。只要不清緩存,不重裝瀏覽器,這數據會一直存在。
數據緩存在本地

File
這個用來導出/引入接口文件在swagger edit裏面進行編輯,也可以輸出YAML/JSON格式。這個如果你是非在線版,編輯一半想下次在編輯,建議先導出備份,避免數據丟失。
下載YAML/JSON
convert to YAML
把編輯區轉換成YAML格式。
convert to YAML

Generate Server
把接口文檔生成服務器文件,導出一個壓縮包,接口文檔生成java、js等服務器文件。很實用工具,讓你寫少很多代碼。
Generate Server

導出spring-boot
導出spring boot

導出nodeJS
導出nodejs

Generate Client
生成查看接口文檔。編寫好下一步就是展示。這裏可以選擇導出什麼格式的接口文檔。
Generate Client

導出html
導出html

文檔編寫語法
文檔是YAML語法來編輯,這裏不解說。這裏提供各字段的中文解釋,大家應該看的懂。對語法不懂,請查看YAML語法 阮一峯

swagger: '2.0'                      # swagger的版本
info:
  title: 文檔標題
  description:  描述
  version: "v1.0"                   # 版本號
  termsOfService: ""                # 文檔支持截止日期
  contact:                          # 聯繫人的信息
    name: ""                        # 聯繫人姓名
    url: ""                         # 聯繫人URL
    email: ""                       # 聯繫人郵箱
  license:                          # 授權信息
    name: ""                        # 授權名稱,例如Apache 2.0
    url: ""                         # 授權URL
host: api.haofly.net                # 域名,可以包含端口,如果不提供host,那麼默認爲提供yaml文件的host
basePath: /                         # 前綴,比如/v1
schemes:                            # 傳輸協議
  - http
  - https

securityDefinitions:                # 安全設置
  api_key:
    type: apiKey
    name: Authorization             # 實際的變量名比如,Authorization
    in: header                      # 認證變量放在哪裏,query或者header
  OauthSecurity:                    # oauth2的話有些參數必須寫全
    type: oauth2
    flow: accessCode                # 可選值爲implicit/password/application/accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      admin: Admin scope
      user: User scope
      media: Media scope
  auth:
    type: oauth2
    description: ""                 # 描述
    authorizationUrl: http://haofly.net/api/oauth/
    name: Authorization             # 實際的變量名比如,Authorization
    tokenUrl:
    flow: implicit                  # oauth2認證的幾種形式,implicit/password/application/accessCode
    scopes:
      write:post: 修改文件
      read:post: 讀取文章

security:                           # 全局的安全設置的一個選擇吧
  auth:
    - write:pets
    - read:pets

consumes:                           # 接收的MIME types列表
  - application/json                # 接收響應的Content-Type
  - application/vnd.github.v3+json

produces:                           # 請求的MIME types列表
  - application/vnd.knight.v1+json  # 請求頭的Accept值
  - text/plain; charset=utf-8
tags:                               # 相當於一個分類
  - name: post  
    description: 關於post的接口

externalDocs:
  description: find more info here
  url: https://haofly.net

paths:                              # 定義接口的url的詳細信息
  /projects/{projectName}:          # 接口後綴,可以定義參數
    get:
      tags:                         # 所屬分類的列表
        - post  
      summary: 接口描述              # 簡介
      description:                  # 詳細介紹
      externalDocs:                 # 這裏也可以加這個
        description:
        url:
      operationId: ""               # 操作的唯一ID
      consumes: [string]            # 可接收的mime type列表
      produces: [string]            # 可發送的mime type列表
      schemes: [string]             # 可接收的協議列表
      deprecated: false             # 該接口是否已經棄用
      security:                     # OAuth2認證用
        - auth: 
            - write:post
            - read: read
      parameters:                   # 接口的參數
        - name: projectName         # 參數名
          in: path                  # 該參數應該在哪個地方,例如path、body、query等,但是需要注意的是如果in body,只能用schema來指向一個定義好的object,而不能直接在這裏定義
          type: string              # 參數類型
          allowEmptyValue: boolean          # 是否允許爲空值
          description: 項目名        # 參數描述
          required: true            # 是否必須
          default: *                # 設置默認值
          maximum: number           # number的最大值
          exclusiveMaximum: boolean # 是否排除最大的那個值
          minimum: number           # number的最小值
          exclusiveMinimum: boolean
          maxLength: integer        # int的最大值
          minLength: integer
          enum: [*]                 # 枚舉值
          items:                    # type爲數組的時候可以定義其項目的類型
        - $ref: "#/parameters/uuidParam"   # 這樣可以直接用定義好的
      responses:                    # 設置響應
        200:                        # 通過http狀態來描述響應
          description: Success      # 該響應的描述
          schema:                   # 定義返回數據的結構
            $ref: '#/definitions/ProjectDataResponse'  # 直接關聯至某個model

  /another: # 另一個接口
      responses:
        200:
            description:
            schema:
              type: object
              properitis:
                data:
                    $ref: '#/definitions/User' # 關聯

definitions:            # Model/Response的定義,這裏的定義不強制要求返回數據必須和這個一致,但是在swagger-ui上,會展示這裏面的字段。
  Product:              # 定義一個model
    type: object        # model類型
    properties:         # 字段列表
      product_id:       # 字段名
        type: integer   # 字段類型
        description:    # 字段描述
      product_name:
        type: string
        description: 
  ProjectDataResponse:
    type: object
    properties:
        data:
            $ref: '#/definitions/ProjectResponse'  # model之間的關聯,表示在data字段裏面包含的是一個ProjectResponse對象
parameters:             # 可以供很多接口使用的params
  limitParam:
    name: limit
    in: query
    description: max records to return
    required: true
    type: integer
    format: int32
responses:              # 可以供很多接口使用的responses
  NotFound:
    description: Entity not found.

參考鏈接
Swagger官網:http://swagger.io/
Swagger Github:https://github.com/swagger-api
Swagger Editor在線demo:http://editor.swagger.io/#/
Swagger UI在線demo:http://petstore.swagger.io/

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章