來源：JarunWang 發(fā)布時間：2018-11-01 14:41:56 閱讀量：917
Swagger Edit介紹
Swagger是專門用來管理接口一個工具。在開發(fā)過程中，接口一直是紛爭的聚焦點，能有效管理接口（保存好記錄、及時更新、方便查看、接口測試）。會讓整個項目開發(fā)效率提升很大。
而其中Swagger Edit是用來編輯接口文檔的小程序，簡單易用。在官網(wǎng)上分為在線編輯和下載代碼線下編輯，兩種編輯方式。Swagger是通過YAML來定義你的接口規(guī)范?？梢酝ㄟ^接口文檔幫你生成不同框架的服務(wù)端和客戶端，方便你mock和契約測試。最后導(dǎo)出JSON格式的API規(guī)范，通過Swagger UI對外發(fā)布。下圖就是Swagger Edit界面：
安裝
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頁面了。
界面介紹
swagger edit界面分為導(dǎo)航欄和工作區(qū)。導(dǎo)航欄是對接口文檔的處理用，下面會介紹到。
工作區(qū)就是我們花時間最多的地方。分為左右區(qū)域，左邊是編輯區(qū)，右邊是顯示區(qū)。左邊編輯區(qū)使用的YAML語法來編寫，只要一修改右邊顯示區(qū)立刻有變化，使用很便捷。進入swagger edit會默認填入一個demo文檔，通常我們只需要修改demo文檔，就能制作我們想要的接口文檔。如下圖：
編寫完文檔點擊展示區(qū)的excute，進行測試接口。如下圖
ps：Swagger Edit修改會后會立即把數(shù)據(jù)保存到瀏覽器Local Storage里面，所以不用擔心關(guān)閉瀏覽器就會把數(shù)據(jù)丟失。只要不清緩存，不重裝瀏覽器，這數(shù)據(jù)會一直存在。
File
這個用來導(dǎo)出/引入接口文件在swagger edit里面進行編輯，也可以輸出YAML/JSON格式。這個如果你是非在線版，編輯一半想下次在編輯，建議先導(dǎo)出備份，避免數(shù)據(jù)丟失。
convert to YAML
把編輯區(qū)轉(zhuǎn)換成YAML格式。
Generate Server
把接口文檔生成服務(wù)器文件，導(dǎo)出一個壓縮包，接口文檔生成java、js等服務(wù)器文件。很實用工具，讓你寫少很多代碼。
導(dǎo)出spring-boot
導(dǎo)出nodeJS
Generate Client
生成查看接口文檔。編寫好下一步就是展示。這里可以選擇導(dǎo)出什么格式的接口文檔。
導(dǎo)出html
文檔編寫語法
文檔是YAML語法來編輯，這里不解說。這里提供各字段的中文解釋，大家應(yīng)該看的懂。對語法不懂，請查看YAML語法 阮一峰
swagger: '2.0' # swagger的版本
info:
title: 文檔標題
description: 描述
version: "v1.0" # 版本號
termsOfService: "" # 文檔支持截止日期
contact: # 聯(lián)系人的信息
name: "" # 聯(lián)系人姓名
url: "" # 聯(lián)系人URL
email: "" # 聯(lián)系人郵箱
license: # 授權(quán)信息
name: "" # 授權(quán)名稱，例如Apache 2.0
url: "" # 授權(quán)URL
host: api.haofly.net # 域名，可以包含端口，如果不提供host，那么默認為提供yaml文件的host
basePath: / # 前綴，比如/v1
schemes: # 傳輸協(xié)議
- http
- https
securityDefinitions: # 安全設(shè)置
api_key:
type: apiKey
name: Authorization # 實際的變量名比如，Authorization
in: header # 認證變量放在哪里，query或者header
OauthSecurity: # oauth2的話有些參數(shù)必須寫全
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: # 全局的安全設(shè)置的一個選擇吧
auth:
- write:pets
- read:pets
consumes: # 接收的MIME types列表
- application/json # 接收響應(yīng)的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: 關(guān)于post的接口
externalDocs:
description: find more info here
url: https://haofly.net
paths: # 定義接口的url的詳細信息
/projects/{projectName}: # 接口后綴，可以定義參數(shù)
get:
tags: # 所屬分類的列表
- post
summary: 接口描述 # 簡介
description: # 詳細介紹
externalDocs: # 這里也可以加這個
description:
url:
operationId: "" # 操作的唯一ID
consumes: [string] # 可接收的mime type列表
produces: [string] # 可發(fā)送的mime type列表
schemes: [string] # 可接收的協(xié)議列表
deprecated: false # 該接口是否已經(jīng)棄用
security: # OAuth2認證用
- auth:
- write:post
- read: read
parameters: # 接口的參數(shù)
- name: projectName # 參數(shù)名
in: path # 該參數(shù)應(yīng)該在哪個地方，例如path、body、query等，但是需要注意的是如果in body，只能用schema來指向一個定義好的object，而不能直接在這里定義
type: string # 參數(shù)類型
allowEmptyValue: boolean # 是否允許為空值
description: 項目名 # 參數(shù)描述
required: true # 是否必須
default: * # 設(shè)置默認值
maximum: number # number的最大值
exclusiveMaximum: boolean # 是否排除最大的那個值
minimum: number # number的最小值
exclusiveMinimum: boolean
maxLength: integer # int的最大值
minLength: integer
enum: [*] # 枚舉值
items: # type為數(shù)組的時候可以定義其項目的類型
- $ref: "#/parameters/uuidParam" # 這樣可以直接用定義好的
responses: # 設(shè)置響應(yīng)
200: # 通過http狀態(tài)來描述響應(yīng)
description: Success # 該響應(yīng)的描述
schema: # 定義返回數(shù)據(jù)的結(jié)構(gòu)
$ref: '#/definitions/ProjectDataResponse' # 直接關(guān)聯(lián)至某個model
/another: # 另一個接口
responses:
200:
description:
schema:
type: object
properitis:
data:
$ref: '#/definitions/User' # 關(guān)聯(lián)
definitions: # Model/Response的定義，這里的定義不強制要求返回數(shù)據(jù)必須和這個一致，但是在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之間的關(guān)聯(lián)，表示在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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
參考
Swagger官網(wǎng)：http://swagger.io/
Swagger Github：https://github.com/swagger-api
Swagger Editor在線demo：http://editor.swagger.io/#/
Swagger UI在線demo：http://petstore.swagger.io/
Swagger UI及 Swagger editor教程 API文檔搭配 Node使用
swagger ui 是一個在線文檔生成和測試的利器,目前發(fā)現(xiàn)最好用的.為啥好用呢?打開 demo, 支持API自動生成同步的在線文檔些文檔可用于項目內(nèi)部API審核方便測試人員了解 AP...
---------------------
作者：JarunWang
來源：CSDN
原文：https://blog.csdn.net/rth362147773/article/details/78992043
版權(quán)聲明：本文為博主原創(chuàng)文章，轉(zhuǎn)載請附上博文鏈接！
13450931319
微信登錄
QQ登錄
微博登錄
售前咨詢
