Swagger Edit介紹
Swagger是專門用來管理接口一個工具。在開發過程當中，接口一直是紛爭的聚焦點，能有效管理接口（保存好記錄、及時更新、方便查看、接口測試）。會讓整個項目開發效率提高很大。
而其中Swagger Edit是用來編輯接口文檔的小程序，簡單易用。在官網上分爲在線編輯和下載代碼線下編輯，兩種編輯方式。Swagger是經過YAML來定義你的接口規範。能夠經過接口文檔幫你生成不一樣框架的服務端和客戶端，方便你mock和契約測試。最後導出JSON格式的API規範，經過Swagger UI對外發布。下圖就是Swagger Edit界面： html
安裝
1.下載而且安裝node.js
2. npm install -g http-server
3. 下載項目https://github.com/swagger-api/swagger-editor 而且解壓。
4. 進入swagger-editor文件夾。運行http-server命令。
5. 進入http://127.0.0.1 就能夠看到swagger頁面了。java
界面介紹
swagger edit界面分爲導航欄和工做區。導航欄是對接口文檔的處理用，下面會介紹到。
工做區就是咱們花時間最多的地方。分爲左右區域，左邊是編輯區，右邊是顯示區。左邊編輯區使用的YAML語法來編寫，只要一修改右邊顯示區馬上有變化，使用很便捷。進入swagger edit會默認填入一個demo文檔，一般咱們只須要修改demo文檔，就能製做咱們想要的接口文檔。以下圖： node
編寫完文檔點擊展現區的excute，進行測試接口。以下圖 git
ps：Swagger Edit修改會後會當即把數據保存到瀏覽器Local Storage裏面，因此不用擔憂關閉瀏覽器就會把數據丟失。只要不清緩存，不重裝瀏覽器，這數據會一直存在。 github
File
這個用來導出/引入接口文件在swagger edit裏面進行編輯，也能夠輸出YAML/JSON格式。這個若是你是非在線版，編輯一半想下次在編輯，建議先導出備份，避免數據丟失。 spring
convert to YAML
把編輯區轉換成YAML格式。 npm
Generate Server
把接口文檔生成服務器文件，導出一個壓縮包，接口文檔生成java、js等服務器文件。很實用工具，讓你寫少不少代碼。 json
導出spring-boot 小程序
導出nodeJS api
Generate Client
生成查看接口文檔。編寫好下一步就是展現。這裏能夠選擇導出什麼格式的接口文檔。
導出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: int32responses: # 能夠供不少接口使用的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/--------------------- 做者：JarunWang 來源：CSDN 原文：https://blog.csdn.net/rth362147773/article/details/78992043 版權聲明：本文爲博主原創文章，轉載請附上博文連接！