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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
| #必要字段！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: 别名
|
参考文章：https://zhuanlan.zhihu.com/p/21353795
相关阅读
程序员晚枫专注AI编程培训，小白看完他和图灵社区合作的教程《30讲 · AI编程训练营》就能上手做AI项目。
🎓 AI 编程实战课程
想系统学习 AI 编程？程序员晚枫的 AI 编程实战课 帮你从零上手！
微信进群