zero-rails_openapi 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: ade759189024d01051f73655ca7f55d14264598c
4
- data.tar.gz: f97aa2a93a2b88af05e8326e5d1ef894a205cc47
3
+ metadata.gz: 7670c75c3357ce813ab3664c7403386a9e544c58
4
+ data.tar.gz: 00f1a35580391046946ce002d39ef66dad3d0a71
5
5
  SHA512:
6
- metadata.gz: 8b9ba73d3704dff23f9e5fc9d515a87ad2e822b7fd08aa9207e9e47d0e47e5ece4ba66bed8514e3465e87ddf761060ed73c2f6cfb8c79be7438a4f7ebe5452eb
7
- data.tar.gz: eb6048d787fbc7f3001e2fe7b47b999e404282b801741c07248ee0a6516c64a24b8790f5093383aa5f816a902178752fd8f830977ba4ee55dc4fc36f5b7e4fdc
6
+ metadata.gz: e149d59f5e44dcf5349f980debf0f000345a3bf398fe9084dda7733305af6a99c42b9aed21f2fc87eabda030ca8e24e0c423a10e8ab2617296ad136dd60bea53
7
+ data.tar.gz: 12e6d7ad092fda104aa439dcf17c64bcb93d5a0e9467c1e5b4a27802d0ff21dc0c4a63c99523958f7bea7f174a877e43a04c0b5d1aad1f446343eb2e46e9a514
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- zero-rails_openapi (1.2.0)
4
+ zero-rails_openapi (1.3.0)
5
5
 
6
6
  GEM
7
7
  remote: https://rubygems.org/
data/README.md CHANGED
@@ -22,12 +22,14 @@ but I dont have enough time now = ▽ =
22
22
  - [Configure](#configure)
23
23
  - [Usage](#usage)
24
24
  - [DSL for documenting your controller](#dsl-for-documenting-your-controller)
25
- - [Generate JSON Documentation File](#generate-json-documentation-file)
25
+ - [Generate JSON documentation file](#generate-json-documentation-file)
26
26
  - [Use Swagger UI(very beautiful web page) to show your Documentation](#use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
27
27
  - [Tricks](#tricks)
28
- - [Write DSL Somewhere Else](#trick1-write-the-dsl-somewhere-else)
29
- - [DRYing](#trick2-drying)
30
- - [Auto Generate Description](#trick3-auto-generate-description)
28
+ - [Write DSL somewhere else](#trick1---write-the-dsl-somewhere-else)
29
+ - [Global DRYing](#trick2---global-drying)
30
+ - [Auto generate description](#trick3---auto-generate-description)
31
+ - [Skip or Use parameters define in api_dry](#trick4---skip-or-use-parameters-define-in-api_dry)
32
+ - [Atuo Generate index/show Actions's Responses Based on DB Schema](#trick5)
31
33
  - [Troubleshooting](#troubleshooting)
32
34
 
33
35
  ## About OAS
@@ -66,7 +68,7 @@ This is the simplest configuration example:
66
68
  # config/initializers/open_api.rb
67
69
  require 'open_api'
68
70
 
69
- OpenApi.configure do |c|
71
+ OpenApi::Config.tap do |c|
70
72
  # [REQUIRED] The output location where .json doc file will be written to.
71
73
  c.file_output_path = 'public/open_api'
72
74
 
@@ -94,7 +96,7 @@ end
94
96
  You can also set the *global configuration(/component)* of OAS:
95
97
  Server Object / Security Scheme Object / Security Requirement Object ...
96
98
 
97
- For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/open_api.rb)
99
+ For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob//examples/open_api.rb)
98
100
 
99
101
  ## Usage
100
102
 
@@ -128,7 +130,7 @@ class Api::V1::ExamplesController < Api::V1::BaseController
128
130
  response '567', 'query result export', :pdf, type: File
129
131
  end
130
132
 
131
- open_api :index, '(SUMMARY) this api blah blah ...' do
133
+ open_api :index, '(SUMMARY) this api blah blah ...', :builder_template1 do
132
134
  this_api_is_invalid! 'this api is expired!'
133
135
  desc 'Optional multiline or single-line Markdown-formatted description',
134
136
  id: 'user id',
@@ -205,10 +207,15 @@ end
205
207
 
206
208
  ```ruby
207
209
  # method signature
208
- open_api method, summary = '', &block
210
+ open_api method, summary = '', options = { }, &block
209
211
  # usage
210
- open_api :index, '(SUMMARY) this api blah blah ...' do; end
212
+ open_api :index, '(SUMMARY) this api blah blah ...', builder: template1 do end
211
213
  ```
214
+ If pass `builder` or `bd` to the third parameter,
215
+ and `generate_jbuilder_file` in your setting file is set `true`,
216
+ ZRO will generate JBuilder file by using specified template that you set
217
+ `template1` in your setting file.
218
+ For example, see: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob//examples/open_api.rb)
212
219
 
213
220
 
214
221
  #### \>\> DSL methods inside *open_api* and *api_dry*'s block ([source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: ApiInfoObj)
@@ -272,11 +279,11 @@ parameters, request body, responses, securities, servers.
272
279
  header! name, type, schema_hash = { }
273
280
  query! name, type, schema_hash = { }
274
281
  # usage
275
- header! :'X-Token', String
282
+ header! :'Token', String
276
283
  query! :done, Boolean, must_be: false, default: true
277
284
  ```
278
285
 
279
- [**>> More About Param DSL <<**](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md)
286
+ [**>> More About Param DSL <<**](https://github.com/zhandao/zero-rails_openapi/blob//parameter.md)
280
287
 
281
288
  - request_body family methods (OAS - [Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#requestBodyObject))
282
289
  - `request_body`
@@ -402,7 +409,7 @@ The DSL methods used to generate the components in this block are:
402
409
  # or (unrecommended)
403
410
  schema :Dog, { id!: Integer, name: String }, dft: { id: 1, name: 'pet' }
404
411
  ```
405
- *: see: [Type](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md#type)
412
+ *: see: [Type](https://github.com/zhandao/zero-rails_openapi/blob//parameter.md#type)
406
413
 
407
414
  ### Generate JSON Documentation File
408
415
 
@@ -454,12 +461,11 @@ end
454
461
 
455
462
  Notes: convention is the file name ends with `_doc.rb`
456
463
 
457
- #### Trick2 - DRYing
464
+ #### Trick2 - Global DRYing
458
465
 
459
- To be written.
466
+ Method `api_dry` is for DRY but its scope is limited to the current controller.
460
467
 
461
- You can look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/auto_gen_dsl.rb) at the moment.
462
- In general is to use method `api_dry`.
468
+ I have no idea of best practices, But you can look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/auto_gen_doc.rb).
463
469
  The implementation of the file is: do `api_dry` when inherits the base controller inside `inherited` method.
464
470
 
465
471
  #### Trick3 - Auto Generate Description
@@ -491,7 +497,23 @@ query :view, String, enum: {
491
497
  'cheap goods': :borrow,
492
498
  }
493
499
  ```
494
- Read this [file](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/auto_gen_desc.rb) to learn more.
500
+ Read this [file](https://github.com/zhandao/zero-rails_openapi/blob/examples/auto_gen_desc.rb) to learn more.
501
+
502
+ #### Trick4 - Skip or Use parameters define in api_dry
503
+
504
+ Pass `skip: []` and `use: []` to `open_api` like following code:
505
+ ```ruby
506
+ open_api :index, 'desc', builder: :index, skip: [ :Token ]
507
+ ```
508
+
509
+ Look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/examples/goods_doc.rb) to learn more.
510
+
511
+ #### Trick5 - Auto Generate index/show Actions's Responses Based on DB Schema
512
+
513
+ Use method `load_schema` in `api_dry`.
514
+
515
+ See this [file](https://github.com/zhandao/zero-rails_openapi/blob/examples/auto_gen_doc.rb#L51) for uasge information.
516
+
495
517
 
496
518
  ## Troubleshooting
497
519
 
@@ -11,18 +11,21 @@ class V1::GoodsDoc < BaseDoc
11
11
  search_type!: 'search field, allows:<br/>'
12
12
  # '1/ name<br/>2/ creator,<br/>3/ category<br/>4/ price<br/>'
13
13
 
14
- # query :view, String, enum: %w[all online offline get borrow]
14
+ # Instead of:
15
+ # query :view, String, enum: %w[all online offline expensive cheap]
15
16
  query :view, String, enum: {
16
17
  'all goods (default)': :all,
17
- 'only online': :online,
18
- 'only offline': :offline,
19
- 'expensive goods': :get,
20
- 'cheap goods': :borrow,
18
+ 'only online': :online,
19
+ 'only offline': :offline,
20
+ 'expensive goods': :expensive,
21
+ 'cheap goods': :cheap,
21
22
  }
22
23
  query :search_type, String, enum: %w[name creator category price]
23
24
  # Same as:
24
25
  # query :search_type, String, desc!: 'search field, allows:<br/>',
25
26
  # enum: %w[name creator category price]
27
+
28
+ # TODO: Support `desc: '', auto_desc: true or [:enum, :must_be]`
26
29
  end
27
30
 
28
31
  end
@@ -0,0 +1,86 @@
1
+ require 'open_api/generator'
2
+
3
+ # Usage: add `include AutoGenDoc` to your base controller.
4
+ module AutoGenDoc
5
+ def self.included(base)
6
+ base.extend ClassMethods
7
+ end
8
+
9
+ module ClassMethods
10
+ def inherited(subclass)
11
+ super
12
+ subclass.class_eval do
13
+ break unless self.name.match? /sController|sDoc/
14
+ ctrl_path "api/#{self.name.sub('Doc', '').downcase.gsub('::', '/')}" if self.name.match? /sDoc/
15
+ open_api_dry
16
+ end
17
+ end
18
+
19
+ private
20
+
21
+ def open_api_dry
22
+ ctrl_path = try(:controller_path) || instance_variable_get('@_ctrl_path')
23
+ ::OpenApi::Generator.get_actions_by_ctrl_path(ctrl_path)&.each do |action|
24
+ api_dry action do
25
+ header! :Token, String, desc: 'user token'
26
+
27
+ # Common :index parameters
28
+ if action == 'index'
29
+ query :page, Integer, desc: 'page, greater than 1', range: { ge: 1 }, dft: 1
30
+ query :rows, Integer, desc: 'data count per page', range: { ge: 1 }, dft: 10
31
+ end
32
+
33
+ # Common :show parameters
34
+ if action == 'show'
35
+ path! :id, Integer, desc: 'id'
36
+ end
37
+
38
+ # Common :destroy parameters
39
+ if action == 'destroy'
40
+ path! :id, Integer, desc: 'id'
41
+ end
42
+
43
+ # Common :update parameters
44
+ if action == 'update'
45
+ path! :id, Integer, desc: 'id'
46
+ end
47
+
48
+ ### Common responses
49
+ # OAS require at least one response on each api.
50
+ # default_response 'default response', :json
51
+ model = Object.const_get(action_path.split('#').first.split('/').last[0..-2].camelize) rescue nil
52
+ type = action.in?(['index', 'show']) ? Array[load_schema(model)] : String
53
+ response '200', 'success', :json, type: {
54
+ code: { type: Integer, dft: 200 },
55
+ msg: { type: String, dft: 'success' },
56
+ total: { type: Integer },
57
+ timestamp: { type: Integer },
58
+ language: { type: String, dft: 'Ruby' },
59
+ data: { type: type }
60
+ }
61
+
62
+
63
+ ### Automatically generate responses based on the agreed error class.
64
+ # The business error-class's implementation see:
65
+ # https://github.com/zhandao/zero-rails/blob/master/lib/business_error/z_error.rb
66
+ # It's usage see:
67
+ # https://github.com/zhandao/zero-rails/blob/master/app/controllers/api/v1/base_controller.rb
68
+ # Then, the following code will auto generate error responses by
69
+ # extracting the specified error classes info, for example,
70
+ # in ExamplesError: `mattr_reader :name_not_found, 'can not find the name', 404`
71
+ # will generate: `"404": { "description": "can not find the name" }`
72
+ ###
73
+ # # api/v1/examples#index => ExamplesError
74
+ # error_class_name = action_path.split('#').first.split('/').last.camelize.concat('Error')
75
+ # error_class = Object.const_get(error_class_name) rescue next
76
+ # errors = error_class.errors
77
+ # cur_errs = (errors[action.to_sym] || []) + (errors[:private] || [ ]) + (errors[:_public] || [ ])
78
+ # cur_errs.each do |error|
79
+ # info = error_class.send(error, :info)
80
+ # response info[:code], info[:msg]
81
+ # end
82
+ end
83
+ end
84
+ end
85
+ end
86
+ end
@@ -0,0 +1,2998 @@
1
+ {
2
+ "openapi": "3.0.0",
3
+ "info": {
4
+ "title": "Zero Rails Apis",
5
+ "version": "0.0.1"
6
+ },
7
+ "servers": [
8
+ {
9
+ "url": "http://localhost:3000",
10
+ "description": "Optional server description, e.g. Main (production) server"
11
+ },
12
+ {
13
+ "url": "http://staging_server",
14
+ "description": "Optional server description, e.g. Internal staging server for testing"
15
+ }
16
+ ],
17
+ "security": [
18
+ {
19
+ "ApiKeyAuth": [
20
+
21
+ ]
22
+ }
23
+ ],
24
+ "tags": [
25
+ {
26
+ "name": "Goods"
27
+ },
28
+ {
29
+ "name": "Permissions"
30
+ },
31
+ {
32
+ "name": "Roles"
33
+ },
34
+ {
35
+ "name": "Categories"
36
+ },
37
+ {
38
+ "name": "Inventories"
39
+ },
40
+ {
41
+ "name": "Stores"
42
+ },
43
+ {
44
+ "name": "Users"
45
+ }
46
+ ],
47
+ "paths": {
48
+ "/api/v1/goods": {
49
+ "get": {
50
+ "description": "Get list of Goods.",
51
+ "summary": "Get list of Goods.",
52
+ "operationId": "index",
53
+ "tags": [
54
+ "Goods"
55
+ ],
56
+ "parameters": [
57
+ {
58
+ "name": "Token",
59
+ "in": "header",
60
+ "required": true,
61
+ "description": "user token",
62
+ "schema": {
63
+ "type": "string"
64
+ }
65
+ },
66
+ {
67
+ "name": "created_start_at",
68
+ "in": "query",
69
+ "required": false,
70
+ "description": "时间起点, YY-MM-DD (HH:MM:SS, 可选)",
71
+ "schema": {
72
+ "type": "string",
73
+ "format": "date-time",
74
+ "as": "start"
75
+ }
76
+ },
77
+ {
78
+ "name": "created_end_at",
79
+ "in": "query",
80
+ "required": false,
81
+ "description": "时间终点, YY-MM-DD (HH:MM:SS, 可选)",
82
+ "schema": {
83
+ "type": "string",
84
+ "format": "date-time",
85
+ "as": "end"
86
+ }
87
+ },
88
+ {
89
+ "name": "page",
90
+ "in": "query",
91
+ "required": false,
92
+ "description": "页数,从 1 开始",
93
+ "schema": {
94
+ "type": "integer",
95
+ "minimum": 1,
96
+ "default": 1
97
+ }
98
+ },
99
+ {
100
+ "name": "rows",
101
+ "in": "query",
102
+ "required": false,
103
+ "description": "per page, 请求的数据条数",
104
+ "schema": {
105
+ "type": "integer",
106
+ "minimum": 1,
107
+ "default": 10
108
+ }
109
+ },
110
+ {
111
+ "name": "view",
112
+ "in": "query",
113
+ "required": false,
114
+ "description": "请求来自的视图,允许值:<br/>1/ 所有物品 (default): all<br/>2/ 上线物品: online<br/>3/ 下线物品: offline",
115
+ "schema": {
116
+ "type": "string",
117
+ "enum": [
118
+ "all",
119
+ "online",
120
+ "offline"
121
+ ],
122
+ "default": "all"
123
+ }
124
+ },
125
+ {
126
+ "name": "search_type",
127
+ "in": "query",
128
+ "required": false,
129
+ "description": "搜索的字段名,允许值:<br/>1/ name<br/>2/ creator<br/>3/ category_name<br/>4/ unit<br/>5/ price",
130
+ "schema": {
131
+ "type": "string",
132
+ "enum": [
133
+ "name",
134
+ "creator",
135
+ "category_name",
136
+ "unit",
137
+ "price"
138
+ ],
139
+ "as": "field"
140
+ }
141
+ },
142
+ {
143
+ "name": "export",
144
+ "in": "query",
145
+ "required": false,
146
+ "description": "是否将查询结果导出 Excel 文件",
147
+ "schema": {
148
+ "type": "boolean"
149
+ }
150
+ }
151
+ ],
152
+ "responses": {
153
+ "200": {
154
+ "description": "success",
155
+ "content": {
156
+ "application/json": {
157
+ "schema": {
158
+ "type": "object",
159
+ "properties": {
160
+ "code": {
161
+ "type": "integer",
162
+ "default": 200
163
+ },
164
+ "msg": {
165
+ "type": "string",
166
+ "default": "success"
167
+ },
168
+ "total": {
169
+ "type": "integer"
170
+ },
171
+ "timestamp": {
172
+ "type": "integer",
173
+ "format": "time",
174
+ "is": "time"
175
+ },
176
+ "language": {
177
+ "type": "string",
178
+ "default": "Ruby"
179
+ },
180
+ "data": {
181
+ "type": "array",
182
+ "items": {
183
+ "type": "object"
184
+ }
185
+ }
186
+ }
187
+ }
188
+ }
189
+ }
190
+ },
191
+ "-1": {
192
+ "description": "invalid token"
193
+ },
194
+ "-10": {
195
+ "description": "role verification failed"
196
+ },
197
+ "-11": {
198
+ "description": "insufficient permission"
199
+ },
200
+ "700": {
201
+ "description": "change online failed"
202
+ },
203
+ "400": {
204
+ "description": "param validation failure"
205
+ }
206
+ }
207
+ },
208
+ "post": {
209
+ "summary": "Create a Good, returns id of the good that was created.",
210
+ "operationId": "create",
211
+ "tags": [
212
+ "Goods"
213
+ ],
214
+ "parameters": [
215
+ {
216
+ "name": "Token",
217
+ "in": "header",
218
+ "required": true,
219
+ "description": "user token",
220
+ "schema": {
221
+ "type": "string"
222
+ }
223
+ }
224
+ ],
225
+ "requestBody": {
226
+ "required": true,
227
+ "description": "for creating a good",
228
+ "content": {
229
+ "multipart/form-data": {
230
+ "schema": {
231
+ "type": "object",
232
+ "properties": {
233
+ "name": {
234
+ "type": "string",
235
+ "description": "名字"
236
+ },
237
+ "category_id": {
238
+ "type": "integer",
239
+ "minimum": 1,
240
+ "as": "cate",
241
+ "not_permit": true,
242
+ "description": "子类 id"
243
+ },
244
+ "unit": {
245
+ "type": "string",
246
+ "description": "单位"
247
+ },
248
+ "price": {
249
+ "type": "number",
250
+ "format": "float",
251
+ "minimum": 0,
252
+ "description": "单价"
253
+ },
254
+ "is_online": {
255
+ "type": "boolean",
256
+ "description": "是否上线?"
257
+ },
258
+ "remarks": {
259
+ "type": "string",
260
+ "description": "其他说明"
261
+ },
262
+ "pic_path": {
263
+ "type": "string",
264
+ "format": "url",
265
+ "is": "url",
266
+ "description": "图片路径"
267
+ }
268
+ },
269
+ "required": [
270
+ "name",
271
+ "category_id",
272
+ "unit",
273
+ "price"
274
+ ]
275
+ }
276
+ }
277
+ }
278
+ },
279
+ "responses": {
280
+ "200": {
281
+ "description": "success",
282
+ "content": {
283
+ "application/json": {
284
+ "schema": {
285
+ "type": "object",
286
+ "properties": {
287
+ "code": {
288
+ "type": "integer",
289
+ "default": 200
290
+ },
291
+ "msg": {
292
+ "type": "string",
293
+ "default": "success"
294
+ },
295
+ "total": {
296
+ "type": "integer"
297
+ },
298
+ "timestamp": {
299
+ "type": "integer",
300
+ "format": "time",
301
+ "is": "time"
302
+ },
303
+ "language": {
304
+ "type": "string",
305
+ "default": "Ruby"
306
+ },
307
+ "data": {
308
+ "type": "array",
309
+ "items": {
310
+ "type": "object"
311
+ }
312
+ }
313
+ }
314
+ }
315
+ }
316
+ }
317
+ },
318
+ "600": {
319
+ "description": "create failed"
320
+ },
321
+ "-1": {
322
+ "description": "invalid token"
323
+ },
324
+ "-10": {
325
+ "description": "role verification failed"
326
+ },
327
+ "-11": {
328
+ "description": "insufficient permission"
329
+ },
330
+ "700": {
331
+ "description": "change online failed"
332
+ },
333
+ "400": {
334
+ "description": "param validation failure"
335
+ }
336
+ }
337
+ }
338
+ },
339
+ "/api/v1/goods/{id}": {
340
+ "get": {
341
+ "summary": "Show a Good.",
342
+ "operationId": "show",
343
+ "tags": [
344
+ "Goods"
345
+ ],
346
+ "parameters": [
347
+ {
348
+ "name": "Token",
349
+ "in": "header",
350
+ "required": true,
351
+ "description": "user token",
352
+ "schema": {
353
+ "type": "string"
354
+ }
355
+ },
356
+ {
357
+ "name": "id",
358
+ "in": "path",
359
+ "required": true,
360
+ "description": "要查询的 id",
361
+ "schema": {
362
+ "type": "integer"
363
+ }
364
+ }
365
+ ],
366
+ "responses": {
367
+ "200": {
368
+ "description": "success",
369
+ "content": {
370
+ "application/json": {
371
+ "schema": {
372
+ "type": "object",
373
+ "properties": {
374
+ "code": {
375
+ "type": "integer",
376
+ "default": 200
377
+ },
378
+ "msg": {
379
+ "type": "string",
380
+ "default": "success"
381
+ },
382
+ "total": {
383
+ "type": "integer"
384
+ },
385
+ "timestamp": {
386
+ "type": "integer",
387
+ "format": "time",
388
+ "is": "time"
389
+ },
390
+ "language": {
391
+ "type": "string",
392
+ "default": "Ruby"
393
+ },
394
+ "data": {
395
+ "type": "array",
396
+ "items": {
397
+ "type": "object"
398
+ }
399
+ }
400
+ }
401
+ }
402
+ }
403
+ }
404
+ },
405
+ "-1": {
406
+ "description": "invalid token"
407
+ },
408
+ "-10": {
409
+ "description": "role verification failed"
410
+ },
411
+ "-11": {
412
+ "description": "insufficient permission"
413
+ },
414
+ "700": {
415
+ "description": "change online failed"
416
+ },
417
+ "400": {
418
+ "description": "param validation failure"
419
+ }
420
+ }
421
+ },
422
+ "patch": {
423
+ "summary": "Update a Good.",
424
+ "operationId": "update",
425
+ "tags": [
426
+ "Goods"
427
+ ],
428
+ "parameters": [
429
+ {
430
+ "name": "Token",
431
+ "in": "header",
432
+ "required": true,
433
+ "description": "user token",
434
+ "schema": {
435
+ "type": "string"
436
+ }
437
+ },
438
+ {
439
+ "name": "id",
440
+ "in": "path",
441
+ "required": true,
442
+ "description": "要更新的 id",
443
+ "schema": {
444
+ "type": "integer"
445
+ }
446
+ }
447
+ ],
448
+ "requestBody": {
449
+ "required": true,
450
+ "description": "for updating a good",
451
+ "content": {
452
+ "multipart/form-data": {
453
+ "schema": {
454
+ "type": "object",
455
+ "properties": {
456
+ "name": {
457
+ "type": "string",
458
+ "description": "名字"
459
+ },
460
+ "category_id": {
461
+ "type": "integer",
462
+ "minimum": 1,
463
+ "as": "cate",
464
+ "not_permit": true,
465
+ "description": "子类 id"
466
+ },
467
+ "unit": {
468
+ "type": "string",
469
+ "description": "单位"
470
+ },
471
+ "price": {
472
+ "type": "number",
473
+ "format": "float",
474
+ "minimum": 0,
475
+ "description": "单价"
476
+ },
477
+ "remarks": {
478
+ "type": "string",
479
+ "description": "其他说明"
480
+ },
481
+ "pic_path": {
482
+ "type": "string",
483
+ "format": "url",
484
+ "is": "url",
485
+ "description": "图片路径"
486
+ },
487
+ "is_online": {
488
+ "type": "boolean",
489
+ "description": "是否上线"
490
+ }
491
+ }
492
+ }
493
+ }
494
+ }
495
+ },
496
+ "responses": {
497
+ "200": {
498
+ "description": "success",
499
+ "content": {
500
+ "application/json": {
501
+ "schema": {
502
+ "type": "object",
503
+ "properties": {
504
+ "code": {
505
+ "type": "integer",
506
+ "default": 200
507
+ },
508
+ "msg": {
509
+ "type": "string",
510
+ "default": "success"
511
+ },
512
+ "total": {
513
+ "type": "integer"
514
+ },
515
+ "timestamp": {
516
+ "type": "integer",
517
+ "format": "time",
518
+ "is": "time"
519
+ },
520
+ "language": {
521
+ "type": "string",
522
+ "default": "Ruby"
523
+ },
524
+ "data": {
525
+ "type": "array",
526
+ "items": {
527
+ "type": "object"
528
+ }
529
+ }
530
+ }
531
+ }
532
+ }
533
+ }
534
+ },
535
+ "601": {
536
+ "description": "update failed"
537
+ },
538
+ "-1": {
539
+ "description": "invalid token"
540
+ },
541
+ "-10": {
542
+ "description": "role verification failed"
543
+ },
544
+ "-11": {
545
+ "description": "insufficient permission"
546
+ },
547
+ "700": {
548
+ "description": "change online failed"
549
+ },
550
+ "400": {
551
+ "description": "param validation failure"
552
+ }
553
+ }
554
+ },
555
+ "delete": {
556
+ "summary": "Delete a Good.",
557
+ "operationId": "destroy",
558
+ "tags": [
559
+ "Goods"
560
+ ],
561
+ "parameters": [
562
+ {
563
+ "name": "Token",
564
+ "in": "header",
565
+ "required": true,
566
+ "description": "user token",
567
+ "schema": {
568
+ "type": "string"
569
+ }
570
+ },
571
+ {
572
+ "name": "id",
573
+ "in": "path",
574
+ "required": true,
575
+ "description": "要删除的 id",
576
+ "schema": {
577
+ "type": "integer"
578
+ }
579
+ }
580
+ ],
581
+ "responses": {
582
+ "200": {
583
+ "description": "success",
584
+ "content": {
585
+ "application/json": {
586
+ "schema": {
587
+ "type": "object",
588
+ "properties": {
589
+ "code": {
590
+ "type": "integer",
591
+ "default": 200
592
+ },
593
+ "msg": {
594
+ "type": "string",
595
+ "default": "success"
596
+ },
597
+ "total": {
598
+ "type": "integer"
599
+ },
600
+ "timestamp": {
601
+ "type": "integer",
602
+ "format": "time",
603
+ "is": "time"
604
+ },
605
+ "language": {
606
+ "type": "string",
607
+ "default": "Ruby"
608
+ },
609
+ "data": {
610
+ "type": "array",
611
+ "items": {
612
+ "type": "object"
613
+ }
614
+ }
615
+ }
616
+ }
617
+ }
618
+ }
619
+ },
620
+ "602": {
621
+ "description": "destroy failed"
622
+ },
623
+ "-1": {
624
+ "description": "invalid token"
625
+ },
626
+ "-10": {
627
+ "description": "role verification failed"
628
+ },
629
+ "-11": {
630
+ "description": "insufficient permission"
631
+ },
632
+ "700": {
633
+ "description": "change online failed"
634
+ },
635
+ "400": {
636
+ "description": "param validation failure"
637
+ }
638
+ }
639
+ }
640
+ },
641
+ "/api/v1/goods/{id}/change_online": {
642
+ "post": {
643
+ "summary": "Change online status of Good, will do: is_online = !is_online.",
644
+ "operationId": "change_online",
645
+ "tags": [
646
+ "Goods"
647
+ ],
648
+ "parameters": [
649
+ {
650
+ "name": "Token",
651
+ "in": "header",
652
+ "required": true,
653
+ "description": "user token",
654
+ "schema": {
655
+ "type": "string"
656
+ }
657
+ },
658
+ {
659
+ "name": "id",
660
+ "in": "path",
661
+ "required": true,
662
+ "description": "要上/下线的物品 id",
663
+ "schema": {
664
+ "type": "integer"
665
+ }
666
+ }
667
+ ],
668
+ "responses": {
669
+ "200": {
670
+ "description": "success",
671
+ "content": {
672
+ "application/json": {
673
+ "schema": {
674
+ "type": "object",
675
+ "properties": {
676
+ "code": {
677
+ "type": "integer",
678
+ "default": 200
679
+ },
680
+ "msg": {
681
+ "type": "string",
682
+ "default": "success"
683
+ },
684
+ "total": {
685
+ "type": "integer"
686
+ },
687
+ "timestamp": {
688
+ "type": "integer",
689
+ "format": "time",
690
+ "is": "time"
691
+ },
692
+ "language": {
693
+ "type": "string",
694
+ "default": "Ruby"
695
+ },
696
+ "data": {
697
+ "type": "array",
698
+ "items": {
699
+ "type": "object"
700
+ }
701
+ }
702
+ }
703
+ }
704
+ }
705
+ }
706
+ },
707
+ "-1": {
708
+ "description": "invalid token"
709
+ },
710
+ "-10": {
711
+ "description": "role verification failed"
712
+ },
713
+ "-11": {
714
+ "description": "insufficient permission"
715
+ },
716
+ "700": {
717
+ "description": "change online failed"
718
+ },
719
+ "400": {
720
+ "description": "param validation failure"
721
+ }
722
+ }
723
+ }
724
+ },
725
+ "/api/v1/permissions": {
726
+ "get": {
727
+ "summary": "Get list of Permissions of specified model",
728
+ "operationId": "index",
729
+ "tags": [
730
+ "Permissions"
731
+ ],
732
+ "parameters": [
733
+ {
734
+ "name": "Token",
735
+ "in": "header",
736
+ "required": true,
737
+ "description": "user token",
738
+ "schema": {
739
+ "type": "string"
740
+ }
741
+ },
742
+ {
743
+ "name": "model",
744
+ "in": "query",
745
+ "required": false,
746
+ "schema": {
747
+ "type": "string",
748
+ "pattern": "^[A-Z]",
749
+ "default": "User"
750
+ }
751
+ }
752
+ ],
753
+ "responses": {
754
+ "200": {
755
+ "description": "success",
756
+ "content": {
757
+ "application/json": {
758
+ "schema": {
759
+ "type": "object",
760
+ "properties": {
761
+ "code": {
762
+ "type": "integer",
763
+ "default": 200
764
+ },
765
+ "msg": {
766
+ "type": "string",
767
+ "default": "success"
768
+ },
769
+ "total": {
770
+ "type": "integer"
771
+ },
772
+ "timestamp": {
773
+ "type": "integer",
774
+ "format": "time",
775
+ "is": "time"
776
+ },
777
+ "language": {
778
+ "type": "string",
779
+ "default": "Ruby"
780
+ },
781
+ "data": {
782
+ "type": "array",
783
+ "items": {
784
+ "type": "object"
785
+ }
786
+ }
787
+ }
788
+ }
789
+ }
790
+ }
791
+ }
792
+ }
793
+ },
794
+ "post": {
795
+ "summary": "POST create a Permission",
796
+ "operationId": "create",
797
+ "tags": [
798
+ "Permissions"
799
+ ],
800
+ "parameters": [
801
+ {
802
+ "name": "Token",
803
+ "in": "header",
804
+ "required": true,
805
+ "description": "user token",
806
+ "schema": {
807
+ "type": "string"
808
+ }
809
+ }
810
+ ],
811
+ "requestBody": {
812
+ "required": true,
813
+ "description": "for creating a permission",
814
+ "content": {
815
+ "multipart/form-data": {
816
+ "schema": {
817
+ "type": "object",
818
+ "properties": {
819
+ "name": {
820
+ "type": "string",
821
+ "description": "name of permission"
822
+ },
823
+ "condition": {
824
+ "type": "string",
825
+ "default": "true",
826
+ "description": "暂不必传"
827
+ },
828
+ "remarks": {
829
+ "type": "string"
830
+ }
831
+ },
832
+ "required": [
833
+ "name"
834
+ ]
835
+ }
836
+ }
837
+ }
838
+ },
839
+ "responses": {
840
+ "200": {
841
+ "description": "success",
842
+ "content": {
843
+ "application/json": {
844
+ "schema": {
845
+ "type": "object",
846
+ "properties": {
847
+ "code": {
848
+ "type": "integer",
849
+ "default": 200
850
+ },
851
+ "msg": {
852
+ "type": "string",
853
+ "default": "success"
854
+ },
855
+ "total": {
856
+ "type": "integer"
857
+ },
858
+ "timestamp": {
859
+ "type": "integer",
860
+ "format": "time",
861
+ "is": "time"
862
+ },
863
+ "language": {
864
+ "type": "string",
865
+ "default": "Ruby"
866
+ },
867
+ "data": {
868
+ "type": "array",
869
+ "items": {
870
+ "type": "object"
871
+ }
872
+ }
873
+ }
874
+ }
875
+ }
876
+ }
877
+ }
878
+ }
879
+ }
880
+ },
881
+ "/api/v1/roles": {
882
+ "get": {
883
+ "summary": "Get list of Roles of specified model",
884
+ "operationId": "index",
885
+ "tags": [
886
+ "Roles"
887
+ ],
888
+ "parameters": [
889
+ {
890
+ "name": "Token",
891
+ "in": "header",
892
+ "required": true,
893
+ "description": "user token",
894
+ "schema": {
895
+ "type": "string"
896
+ }
897
+ },
898
+ {
899
+ "name": "model",
900
+ "in": "query",
901
+ "required": false,
902
+ "schema": {
903
+ "type": "string",
904
+ "pattern": "^[A-Z]",
905
+ "default": "Admin"
906
+ }
907
+ }
908
+ ],
909
+ "responses": {
910
+ "200": {
911
+ "description": "success",
912
+ "content": {
913
+ "application/json": {
914
+ "schema": {
915
+ "type": "object",
916
+ "properties": {
917
+ "code": {
918
+ "type": "integer",
919
+ "default": 200
920
+ },
921
+ "msg": {
922
+ "type": "string",
923
+ "default": "success"
924
+ },
925
+ "total": {
926
+ "type": "integer"
927
+ },
928
+ "timestamp": {
929
+ "type": "integer",
930
+ "format": "time",
931
+ "is": "time"
932
+ },
933
+ "language": {
934
+ "type": "string",
935
+ "default": "Ruby"
936
+ },
937
+ "data": {
938
+ "type": "array",
939
+ "items": {
940
+ "type": "object"
941
+ }
942
+ }
943
+ }
944
+ }
945
+ }
946
+ }
947
+ }
948
+ }
949
+ },
950
+ "post": {
951
+ "summary": "POST create a Role",
952
+ "operationId": "create",
953
+ "tags": [
954
+ "Roles"
955
+ ],
956
+ "parameters": [
957
+ {
958
+ "name": "Token",
959
+ "in": "header",
960
+ "required": true,
961
+ "description": "user token",
962
+ "schema": {
963
+ "type": "string"
964
+ }
965
+ }
966
+ ],
967
+ "requestBody": {
968
+ "required": true,
969
+ "description": "for creating a role",
970
+ "content": {
971
+ "multipart/form-data": {
972
+ "schema": {
973
+ "type": "object",
974
+ "properties": {
975
+ "name": {
976
+ "type": "string",
977
+ "description": "name of role"
978
+ },
979
+ "condition": {
980
+ "type": "string",
981
+ "default": "true",
982
+ "description": "暂不必传"
983
+ },
984
+ "remarks": {
985
+ "type": "string"
986
+ }
987
+ },
988
+ "required": [
989
+ "name"
990
+ ]
991
+ }
992
+ }
993
+ }
994
+ },
995
+ "responses": {
996
+ "200": {
997
+ "description": "success",
998
+ "content": {
999
+ "application/json": {
1000
+ "schema": {
1001
+ "type": "object",
1002
+ "properties": {
1003
+ "code": {
1004
+ "type": "integer",
1005
+ "default": 200
1006
+ },
1007
+ "msg": {
1008
+ "type": "string",
1009
+ "default": "success"
1010
+ },
1011
+ "total": {
1012
+ "type": "integer"
1013
+ },
1014
+ "timestamp": {
1015
+ "type": "integer",
1016
+ "format": "time",
1017
+ "is": "time"
1018
+ },
1019
+ "language": {
1020
+ "type": "string",
1021
+ "default": "Ruby"
1022
+ },
1023
+ "data": {
1024
+ "type": "array",
1025
+ "items": {
1026
+ "type": "object"
1027
+ }
1028
+ }
1029
+ }
1030
+ }
1031
+ }
1032
+ }
1033
+ }
1034
+ }
1035
+ }
1036
+ },
1037
+ "/api/v1/roles/{id}/permissions": {
1038
+ "post": {
1039
+ "summary": "GET Permissions of specified role",
1040
+ "operationId": "permissions",
1041
+ "tags": [
1042
+ "Roles"
1043
+ ],
1044
+ "parameters": [
1045
+ {
1046
+ "name": "Token",
1047
+ "in": "header",
1048
+ "required": true,
1049
+ "description": "user token",
1050
+ "schema": {
1051
+ "type": "string"
1052
+ }
1053
+ },
1054
+ {
1055
+ "name": "id",
1056
+ "in": "path",
1057
+ "required": true,
1058
+ "description": "要查询的 role id",
1059
+ "schema": {
1060
+ "type": "integer"
1061
+ }
1062
+ }
1063
+ ],
1064
+ "responses": {
1065
+ "200": {
1066
+ "description": "success",
1067
+ "content": {
1068
+ "application/json": {
1069
+ "schema": {
1070
+ "type": "object",
1071
+ "properties": {
1072
+ "code": {
1073
+ "type": "integer",
1074
+ "default": 200
1075
+ },
1076
+ "msg": {
1077
+ "type": "string",
1078
+ "default": "success"
1079
+ },
1080
+ "total": {
1081
+ "type": "integer"
1082
+ },
1083
+ "timestamp": {
1084
+ "type": "integer",
1085
+ "format": "time",
1086
+ "is": "time"
1087
+ },
1088
+ "language": {
1089
+ "type": "string",
1090
+ "default": "Ruby"
1091
+ },
1092
+ "data": {
1093
+ "type": "array",
1094
+ "items": {
1095
+ "type": "object"
1096
+ }
1097
+ }
1098
+ }
1099
+ }
1100
+ }
1101
+ }
1102
+ }
1103
+ }
1104
+ }
1105
+ },
1106
+ "/api/v1/roles/{id}/permissions/add": {
1107
+ "post": {
1108
+ "summary": "POST add Permissions to specified role",
1109
+ "operationId": "permissions_add",
1110
+ "tags": [
1111
+ "Roles"
1112
+ ],
1113
+ "parameters": [
1114
+ {
1115
+ "name": "Token",
1116
+ "in": "header",
1117
+ "required": true,
1118
+ "description": "user token",
1119
+ "schema": {
1120
+ "type": "string"
1121
+ }
1122
+ },
1123
+ {
1124
+ "name": "id",
1125
+ "in": "path",
1126
+ "required": true,
1127
+ "description": "role id",
1128
+ "schema": {
1129
+ "type": "integer"
1130
+ }
1131
+ }
1132
+ ],
1133
+ "requestBody": {
1134
+ "required": true,
1135
+ "description": "for adding permissions to role",
1136
+ "content": {
1137
+ "multipart/form-data": {
1138
+ "schema": {
1139
+ "type": "object",
1140
+ "properties": {
1141
+ "permission_ids": {
1142
+ "type": "array",
1143
+ "items": {
1144
+ "type": "integer",
1145
+ "minimum": 1
1146
+ },
1147
+ "minLength": 1
1148
+ }
1149
+ },
1150
+ "required": [
1151
+ "permission_ids"
1152
+ ]
1153
+ }
1154
+ }
1155
+ }
1156
+ },
1157
+ "responses": {
1158
+ "200": {
1159
+ "description": "success",
1160
+ "content": {
1161
+ "application/json": {
1162
+ "schema": {
1163
+ "type": "object",
1164
+ "properties": {
1165
+ "code": {
1166
+ "type": "integer",
1167
+ "default": 200
1168
+ },
1169
+ "msg": {
1170
+ "type": "string",
1171
+ "default": "success"
1172
+ },
1173
+ "total": {
1174
+ "type": "integer"
1175
+ },
1176
+ "timestamp": {
1177
+ "type": "integer",
1178
+ "format": "time",
1179
+ "is": "time"
1180
+ },
1181
+ "language": {
1182
+ "type": "string",
1183
+ "default": "Ruby"
1184
+ },
1185
+ "data": {
1186
+ "type": "array",
1187
+ "items": {
1188
+ "type": "object"
1189
+ }
1190
+ }
1191
+ }
1192
+ }
1193
+ }
1194
+ }
1195
+ }
1196
+ }
1197
+ }
1198
+ },
1199
+ "/api/v1/roles/{id}/permissions/remove": {
1200
+ "post": {
1201
+ "summary": "POST remove Permissions from specified role",
1202
+ "operationId": "permissions_remove",
1203
+ "tags": [
1204
+ "Roles"
1205
+ ],
1206
+ "parameters": [
1207
+ {
1208
+ "name": "Token",
1209
+ "in": "header",
1210
+ "required": true,
1211
+ "description": "user token",
1212
+ "schema": {
1213
+ "type": "string"
1214
+ }
1215
+ },
1216
+ {
1217
+ "name": "id",
1218
+ "in": "path",
1219
+ "required": true,
1220
+ "description": "role id",
1221
+ "schema": {
1222
+ "type": "integer"
1223
+ }
1224
+ }
1225
+ ],
1226
+ "requestBody": {
1227
+ "required": true,
1228
+ "description": "for removing permissions from the role",
1229
+ "content": {
1230
+ "multipart/form-data": {
1231
+ "schema": {
1232
+ "type": "object",
1233
+ "properties": {
1234
+ "permission_ids": {
1235
+ "type": "array",
1236
+ "items": {
1237
+ "type": "integer",
1238
+ "minimum": 1
1239
+ },
1240
+ "minLength": 1
1241
+ }
1242
+ },
1243
+ "required": [
1244
+ "permission_ids"
1245
+ ]
1246
+ }
1247
+ }
1248
+ }
1249
+ },
1250
+ "responses": {
1251
+ "200": {
1252
+ "description": "success",
1253
+ "content": {
1254
+ "application/json": {
1255
+ "schema": {
1256
+ "type": "object",
1257
+ "properties": {
1258
+ "code": {
1259
+ "type": "integer",
1260
+ "default": 200
1261
+ },
1262
+ "msg": {
1263
+ "type": "string",
1264
+ "default": "success"
1265
+ },
1266
+ "total": {
1267
+ "type": "integer"
1268
+ },
1269
+ "timestamp": {
1270
+ "type": "integer",
1271
+ "format": "time",
1272
+ "is": "time"
1273
+ },
1274
+ "language": {
1275
+ "type": "string",
1276
+ "default": "Ruby"
1277
+ },
1278
+ "data": {
1279
+ "type": "array",
1280
+ "items": {
1281
+ "type": "object"
1282
+ }
1283
+ }
1284
+ }
1285
+ }
1286
+ }
1287
+ }
1288
+ }
1289
+ }
1290
+ }
1291
+ },
1292
+ "/api/v1/categories": {
1293
+ "get": {
1294
+ "summary": "Get list of Categories.",
1295
+ "operationId": "index",
1296
+ "tags": [
1297
+ "Categories"
1298
+ ],
1299
+ "parameters": [
1300
+ {
1301
+ "name": "page",
1302
+ "in": "query",
1303
+ "required": false,
1304
+ "description": "偏移量,从 0 开始",
1305
+ "schema": {
1306
+ "type": "integer",
1307
+ "minimum": 1
1308
+ }
1309
+ },
1310
+ {
1311
+ "name": "rows",
1312
+ "in": "query",
1313
+ "required": false,
1314
+ "description": "per page, 请求的数据条数",
1315
+ "schema": {
1316
+ "type": "integer",
1317
+ "minimum": 1
1318
+ }
1319
+ }
1320
+ ],
1321
+ "responses": {
1322
+ "200": {
1323
+ "description": "success",
1324
+ "content": {
1325
+ "application/json": {
1326
+ "schema": {
1327
+ "type": "object",
1328
+ "properties": {
1329
+ "code": {
1330
+ "type": "integer",
1331
+ "default": 200
1332
+ },
1333
+ "msg": {
1334
+ "type": "string",
1335
+ "default": "success"
1336
+ },
1337
+ "total": {
1338
+ "type": "integer"
1339
+ },
1340
+ "timestamp": {
1341
+ "type": "integer",
1342
+ "format": "time",
1343
+ "is": "time"
1344
+ },
1345
+ "language": {
1346
+ "type": "string",
1347
+ "default": "Ruby"
1348
+ },
1349
+ "data": {
1350
+ "type": "array",
1351
+ "items": {
1352
+ "type": "object"
1353
+ }
1354
+ }
1355
+ }
1356
+ }
1357
+ }
1358
+ }
1359
+ },
1360
+ "-1": {
1361
+ "description": "invalid token"
1362
+ },
1363
+ "-10": {
1364
+ "description": "role verification failed"
1365
+ },
1366
+ "-11": {
1367
+ "description": "insufficient permission"
1368
+ },
1369
+ "400": {
1370
+ "description": "param validation failure"
1371
+ }
1372
+ }
1373
+ },
1374
+ "post": {
1375
+ "summary": "Create a Category, returns id of the category that was created.",
1376
+ "operationId": "create",
1377
+ "tags": [
1378
+ "Categories"
1379
+ ],
1380
+ "parameters": [
1381
+ {
1382
+ "name": "Token",
1383
+ "in": "header",
1384
+ "required": true,
1385
+ "description": "user token",
1386
+ "schema": {
1387
+ "type": "string"
1388
+ }
1389
+ }
1390
+ ],
1391
+ "requestBody": {
1392
+ "required": true,
1393
+ "description": "for creating a category",
1394
+ "content": {
1395
+ "multipart/form-data": {
1396
+ "schema": {
1397
+ "type": "object",
1398
+ "properties": {
1399
+ "name": {
1400
+ "type": "string",
1401
+ "description": "名字"
1402
+ },
1403
+ "is_smaller": {
1404
+ "type": "boolean",
1405
+ "description": "icon name"
1406
+ },
1407
+ "icon_name": {
1408
+ "type": "string",
1409
+ "description": "是否二级分类?"
1410
+ },
1411
+ "base_id": {
1412
+ "type": "integer",
1413
+ "description": "一级分类的 id"
1414
+ }
1415
+ },
1416
+ "required": [
1417
+ "name",
1418
+ "is_smaller"
1419
+ ]
1420
+ }
1421
+ }
1422
+ }
1423
+ },
1424
+ "responses": {
1425
+ "200": {
1426
+ "description": "success",
1427
+ "content": {
1428
+ "application/json": {
1429
+ "schema": {
1430
+ "type": "object",
1431
+ "properties": {
1432
+ "code": {
1433
+ "type": "integer",
1434
+ "default": 200
1435
+ },
1436
+ "msg": {
1437
+ "type": "string",
1438
+ "default": "success"
1439
+ },
1440
+ "total": {
1441
+ "type": "integer"
1442
+ },
1443
+ "timestamp": {
1444
+ "type": "integer",
1445
+ "format": "time",
1446
+ "is": "time"
1447
+ },
1448
+ "language": {
1449
+ "type": "string",
1450
+ "default": "Ruby"
1451
+ },
1452
+ "data": {
1453
+ "type": "array",
1454
+ "items": {
1455
+ "type": "object"
1456
+ }
1457
+ }
1458
+ }
1459
+ }
1460
+ }
1461
+ }
1462
+ },
1463
+ "600": {
1464
+ "description": "create failed"
1465
+ },
1466
+ "-1": {
1467
+ "description": "invalid token"
1468
+ },
1469
+ "-10": {
1470
+ "description": "role verification failed"
1471
+ },
1472
+ "-11": {
1473
+ "description": "insufficient permission"
1474
+ },
1475
+ "400": {
1476
+ "description": "param validation failure"
1477
+ }
1478
+ }
1479
+ }
1480
+ },
1481
+ "/api/v1/category_list": {
1482
+ "get": {
1483
+ "summary": "Get nested list of Categories.",
1484
+ "operationId": "nested_list",
1485
+ "tags": [
1486
+ "Categories"
1487
+ ],
1488
+ "responses": {
1489
+ "200": {
1490
+ "description": "success",
1491
+ "content": {
1492
+ "application/json": {
1493
+ "schema": {
1494
+ "type": "object",
1495
+ "properties": {
1496
+ "code": {
1497
+ "type": "integer",
1498
+ "default": 200
1499
+ },
1500
+ "msg": {
1501
+ "type": "string",
1502
+ "default": "success"
1503
+ },
1504
+ "total": {
1505
+ "type": "integer"
1506
+ },
1507
+ "timestamp": {
1508
+ "type": "integer",
1509
+ "format": "time",
1510
+ "is": "time"
1511
+ },
1512
+ "language": {
1513
+ "type": "string",
1514
+ "default": "Ruby"
1515
+ },
1516
+ "data": {
1517
+ "type": "array",
1518
+ "items": {
1519
+ "type": "object"
1520
+ }
1521
+ }
1522
+ }
1523
+ }
1524
+ }
1525
+ }
1526
+ },
1527
+ "-1": {
1528
+ "description": "invalid token"
1529
+ },
1530
+ "-10": {
1531
+ "description": "role verification failed"
1532
+ },
1533
+ "-11": {
1534
+ "description": "insufficient permission"
1535
+ },
1536
+ "400": {
1537
+ "description": "param validation failure"
1538
+ }
1539
+ }
1540
+ }
1541
+ },
1542
+ "/api/v1/categories/{id}": {
1543
+ "patch": {
1544
+ "summary": "Update a Category.",
1545
+ "operationId": "update",
1546
+ "tags": [
1547
+ "Categories"
1548
+ ],
1549
+ "parameters": [
1550
+ {
1551
+ "name": "Token",
1552
+ "in": "header",
1553
+ "required": true,
1554
+ "description": "user token",
1555
+ "schema": {
1556
+ "type": "string"
1557
+ }
1558
+ },
1559
+ {
1560
+ "name": "id",
1561
+ "in": "path",
1562
+ "required": true,
1563
+ "description": "要更新的 id",
1564
+ "schema": {
1565
+ "type": "integer"
1566
+ }
1567
+ }
1568
+ ],
1569
+ "requestBody": {
1570
+ "required": true,
1571
+ "description": "for creating a category",
1572
+ "content": {
1573
+ "multipart/form-data": {
1574
+ "schema": {
1575
+ "type": "object",
1576
+ "properties": {
1577
+ "name": {
1578
+ "type": "string",
1579
+ "description": "名字"
1580
+ },
1581
+ "is_smaller": {
1582
+ "type": "boolean",
1583
+ "description": "icon name"
1584
+ },
1585
+ "icon_name": {
1586
+ "type": "string",
1587
+ "description": "是否二级分类?"
1588
+ },
1589
+ "base_id": {
1590
+ "type": "integer",
1591
+ "description": "一级分类的 id"
1592
+ }
1593
+ }
1594
+ }
1595
+ }
1596
+ }
1597
+ },
1598
+ "responses": {
1599
+ "200": {
1600
+ "description": "success",
1601
+ "content": {
1602
+ "application/json": {
1603
+ "schema": {
1604
+ "type": "object",
1605
+ "properties": {
1606
+ "code": {
1607
+ "type": "integer",
1608
+ "default": 200
1609
+ },
1610
+ "msg": {
1611
+ "type": "string",
1612
+ "default": "success"
1613
+ },
1614
+ "total": {
1615
+ "type": "integer"
1616
+ },
1617
+ "timestamp": {
1618
+ "type": "integer",
1619
+ "format": "time",
1620
+ "is": "time"
1621
+ },
1622
+ "language": {
1623
+ "type": "string",
1624
+ "default": "Ruby"
1625
+ },
1626
+ "data": {
1627
+ "type": "array",
1628
+ "items": {
1629
+ "type": "object"
1630
+ }
1631
+ }
1632
+ }
1633
+ }
1634
+ }
1635
+ }
1636
+ },
1637
+ "601": {
1638
+ "description": "update failed"
1639
+ },
1640
+ "-1": {
1641
+ "description": "invalid token"
1642
+ },
1643
+ "-10": {
1644
+ "description": "role verification failed"
1645
+ },
1646
+ "-11": {
1647
+ "description": "insufficient permission"
1648
+ },
1649
+ "400": {
1650
+ "description": "param validation failure"
1651
+ }
1652
+ }
1653
+ },
1654
+ "delete": {
1655
+ "summary": "Delete a Category.",
1656
+ "operationId": "destroy",
1657
+ "tags": [
1658
+ "Categories"
1659
+ ],
1660
+ "parameters": [
1661
+ {
1662
+ "name": "Token",
1663
+ "in": "header",
1664
+ "required": true,
1665
+ "description": "user token",
1666
+ "schema": {
1667
+ "type": "string"
1668
+ }
1669
+ },
1670
+ {
1671
+ "name": "id",
1672
+ "in": "path",
1673
+ "required": true,
1674
+ "description": "要删除的 id",
1675
+ "schema": {
1676
+ "type": "integer"
1677
+ }
1678
+ }
1679
+ ],
1680
+ "responses": {
1681
+ "200": {
1682
+ "description": "success",
1683
+ "content": {
1684
+ "application/json": {
1685
+ "schema": {
1686
+ "type": "object",
1687
+ "properties": {
1688
+ "code": {
1689
+ "type": "integer",
1690
+ "default": 200
1691
+ },
1692
+ "msg": {
1693
+ "type": "string",
1694
+ "default": "success"
1695
+ },
1696
+ "total": {
1697
+ "type": "integer"
1698
+ },
1699
+ "timestamp": {
1700
+ "type": "integer",
1701
+ "format": "time",
1702
+ "is": "time"
1703
+ },
1704
+ "language": {
1705
+ "type": "string",
1706
+ "default": "Ruby"
1707
+ },
1708
+ "data": {
1709
+ "type": "array",
1710
+ "items": {
1711
+ "type": "object"
1712
+ }
1713
+ }
1714
+ }
1715
+ }
1716
+ }
1717
+ }
1718
+ },
1719
+ "602": {
1720
+ "description": "destroy failed"
1721
+ },
1722
+ "-1": {
1723
+ "description": "invalid token"
1724
+ },
1725
+ "-10": {
1726
+ "description": "role verification failed"
1727
+ },
1728
+ "-11": {
1729
+ "description": "insufficient permission"
1730
+ },
1731
+ "400": {
1732
+ "description": "param validation failure"
1733
+ }
1734
+ }
1735
+ }
1736
+ },
1737
+ "/api/v1/inventories": {
1738
+ "get": {
1739
+ "description": "Get list of Goods",
1740
+ "summary": "Get list of Inventories.",
1741
+ "operationId": "index",
1742
+ "tags": [
1743
+ "Inventories"
1744
+ ],
1745
+ "parameters": [
1746
+ {
1747
+ "name": "created_start_at",
1748
+ "in": "query",
1749
+ "required": false,
1750
+ "description": "时间起点, YY-MM-DD (HH:MM:SS, 可选)",
1751
+ "schema": {
1752
+ "type": "string",
1753
+ "format": "date-time",
1754
+ "as": "start"
1755
+ }
1756
+ },
1757
+ {
1758
+ "name": "created_end_at",
1759
+ "in": "query",
1760
+ "required": false,
1761
+ "description": "时间终点, YY-MM-DD (HH:MM:SS, 可选)",
1762
+ "schema": {
1763
+ "type": "string",
1764
+ "format": "date-time",
1765
+ "as": "end"
1766
+ }
1767
+ },
1768
+ {
1769
+ "name": "page",
1770
+ "in": "query",
1771
+ "required": false,
1772
+ "description": "页数,从 1 开始",
1773
+ "schema": {
1774
+ "type": "integer",
1775
+ "minimum": 1,
1776
+ "default": 1
1777
+ }
1778
+ },
1779
+ {
1780
+ "name": "rows",
1781
+ "in": "query",
1782
+ "required": false,
1783
+ "description": "per page, 请求的数据条数",
1784
+ "schema": {
1785
+ "type": "integer",
1786
+ "minimum": 1,
1787
+ "default": 10
1788
+ }
1789
+ },
1790
+ {
1791
+ "name": "store_code",
1792
+ "in": "query",
1793
+ "required": true,
1794
+ "description": "商店代号",
1795
+ "schema": {
1796
+ "type": "string"
1797
+ }
1798
+ },
1799
+ {
1800
+ "name": "search_type",
1801
+ "in": "query",
1802
+ "required": false,
1803
+ "description": "搜索的字段名,允许值:<br/>1/ name<br/>2/ creator<br/>3/ category_name<br/>4/ unit<br/>5/ price",
1804
+ "schema": {
1805
+ "type": "string",
1806
+ "enum": [
1807
+ "name",
1808
+ "creator",
1809
+ "category_name",
1810
+ "unit",
1811
+ "price"
1812
+ ],
1813
+ "as": "field"
1814
+ }
1815
+ },
1816
+ {
1817
+ "name": "export",
1818
+ "in": "query",
1819
+ "required": false,
1820
+ "description": "是否将查询结果导出 Excel 文件",
1821
+ "schema": {
1822
+ "type": "boolean"
1823
+ }
1824
+ }
1825
+ ],
1826
+ "responses": {
1827
+ "200": {
1828
+ "description": "success",
1829
+ "content": {
1830
+ "application/json": {
1831
+ "schema": {
1832
+ "type": "object",
1833
+ "properties": {
1834
+ "code": {
1835
+ "type": "integer",
1836
+ "default": 200
1837
+ },
1838
+ "msg": {
1839
+ "type": "string",
1840
+ "default": "success"
1841
+ },
1842
+ "total": {
1843
+ "type": "integer"
1844
+ },
1845
+ "timestamp": {
1846
+ "type": "integer",
1847
+ "format": "time",
1848
+ "is": "time"
1849
+ },
1850
+ "language": {
1851
+ "type": "string",
1852
+ "default": "Ruby"
1853
+ },
1854
+ "data": {
1855
+ "type": "array",
1856
+ "items": {
1857
+ "type": "object"
1858
+ }
1859
+ }
1860
+ }
1861
+ }
1862
+ }
1863
+ }
1864
+ }
1865
+ }
1866
+ }
1867
+ },
1868
+ "/api/v1/stores": {
1869
+ "get": {
1870
+ "summary": "Get list of Stores.",
1871
+ "operationId": "index",
1872
+ "tags": [
1873
+ "Stores"
1874
+ ],
1875
+ "parameters": [
1876
+ {
1877
+ "name": "page",
1878
+ "in": "query",
1879
+ "required": false,
1880
+ "description": "偏移量,从 0 开始",
1881
+ "schema": {
1882
+ "type": "integer",
1883
+ "minimum": 1
1884
+ }
1885
+ },
1886
+ {
1887
+ "name": "rows",
1888
+ "in": "query",
1889
+ "required": false,
1890
+ "description": "per page, 请求的数据条数",
1891
+ "schema": {
1892
+ "type": "integer",
1893
+ "minimum": 1
1894
+ }
1895
+ }
1896
+ ],
1897
+ "responses": {
1898
+ "200": {
1899
+ "description": "success",
1900
+ "content": {
1901
+ "application/json": {
1902
+ "schema": {
1903
+ "type": "object",
1904
+ "properties": {
1905
+ "code": {
1906
+ "type": "integer",
1907
+ "default": 200
1908
+ },
1909
+ "msg": {
1910
+ "type": "string",
1911
+ "default": "success"
1912
+ },
1913
+ "total": {
1914
+ "type": "integer"
1915
+ },
1916
+ "timestamp": {
1917
+ "type": "integer",
1918
+ "format": "time",
1919
+ "is": "time"
1920
+ },
1921
+ "language": {
1922
+ "type": "string",
1923
+ "default": "Ruby"
1924
+ },
1925
+ "data": {
1926
+ "type": "array",
1927
+ "items": {
1928
+ "type": "object"
1929
+ }
1930
+ }
1931
+ }
1932
+ }
1933
+ }
1934
+ }
1935
+ },
1936
+ "-1": {
1937
+ "description": "invalid token"
1938
+ },
1939
+ "-10": {
1940
+ "description": "role verification failed"
1941
+ },
1942
+ "-11": {
1943
+ "description": "insufficient permission"
1944
+ },
1945
+ "400": {
1946
+ "description": "param validation failure"
1947
+ }
1948
+ }
1949
+ },
1950
+ "post": {
1951
+ "summary": "Create a Store, returns id of the store that was created.",
1952
+ "operationId": "create",
1953
+ "tags": [
1954
+ "Stores"
1955
+ ],
1956
+ "parameters": [
1957
+ {
1958
+ "name": "Token",
1959
+ "in": "header",
1960
+ "required": true,
1961
+ "description": "user token",
1962
+ "schema": {
1963
+ "type": "string"
1964
+ }
1965
+ }
1966
+ ],
1967
+ "requestBody": {
1968
+ "required": true,
1969
+ "description": "for creating a store",
1970
+ "content": {
1971
+ "multipart/form-data": {
1972
+ "schema": {
1973
+ "type": "object",
1974
+ "properties": {
1975
+ "code": {
1976
+ "type": "string",
1977
+ "description": "商店代号"
1978
+ },
1979
+ "addr": {
1980
+ "type": "string",
1981
+ "description": "对应的商店地址"
1982
+ }
1983
+ },
1984
+ "required": [
1985
+ "code",
1986
+ "addr"
1987
+ ]
1988
+ }
1989
+ }
1990
+ }
1991
+ },
1992
+ "responses": {
1993
+ "200": {
1994
+ "description": "success",
1995
+ "content": {
1996
+ "application/json": {
1997
+ "schema": {
1998
+ "type": "object",
1999
+ "properties": {
2000
+ "code": {
2001
+ "type": "integer",
2002
+ "default": 200
2003
+ },
2004
+ "msg": {
2005
+ "type": "string",
2006
+ "default": "success"
2007
+ },
2008
+ "total": {
2009
+ "type": "integer"
2010
+ },
2011
+ "timestamp": {
2012
+ "type": "integer",
2013
+ "format": "time",
2014
+ "is": "time"
2015
+ },
2016
+ "language": {
2017
+ "type": "string",
2018
+ "default": "Ruby"
2019
+ },
2020
+ "data": {
2021
+ "type": "array",
2022
+ "items": {
2023
+ "type": "object"
2024
+ }
2025
+ }
2026
+ }
2027
+ }
2028
+ }
2029
+ }
2030
+ },
2031
+ "600": {
2032
+ "description": "create failed"
2033
+ },
2034
+ "-1": {
2035
+ "description": "invalid token"
2036
+ },
2037
+ "-10": {
2038
+ "description": "role verification failed"
2039
+ },
2040
+ "-11": {
2041
+ "description": "insufficient permission"
2042
+ },
2043
+ "400": {
2044
+ "description": "param validation failure"
2045
+ }
2046
+ }
2047
+ }
2048
+ },
2049
+ "/api/v1/stores/{id}": {
2050
+ "get": {
2051
+ "summary": "Show a Store.",
2052
+ "operationId": "show",
2053
+ "tags": [
2054
+ "Stores"
2055
+ ],
2056
+ "responses": {
2057
+ "200": {
2058
+ "description": "success",
2059
+ "content": {
2060
+ "application/json": {
2061
+ "schema": {
2062
+ "type": "object",
2063
+ "properties": {
2064
+ "code": {
2065
+ "type": "integer",
2066
+ "default": 200
2067
+ },
2068
+ "msg": {
2069
+ "type": "string",
2070
+ "default": "success"
2071
+ },
2072
+ "total": {
2073
+ "type": "integer"
2074
+ },
2075
+ "timestamp": {
2076
+ "type": "integer",
2077
+ "format": "time",
2078
+ "is": "time"
2079
+ },
2080
+ "language": {
2081
+ "type": "string",
2082
+ "default": "Ruby"
2083
+ },
2084
+ "data": {
2085
+ "type": "array",
2086
+ "items": {
2087
+ "type": "object"
2088
+ }
2089
+ }
2090
+ }
2091
+ }
2092
+ }
2093
+ }
2094
+ },
2095
+ "-1": {
2096
+ "description": "invalid token"
2097
+ },
2098
+ "-10": {
2099
+ "description": "role verification failed"
2100
+ },
2101
+ "-11": {
2102
+ "description": "insufficient permission"
2103
+ },
2104
+ "400": {
2105
+ "description": "param validation failure"
2106
+ }
2107
+ }
2108
+ },
2109
+ "patch": {
2110
+ "summary": "Update a Store.",
2111
+ "operationId": "update",
2112
+ "tags": [
2113
+ "Stores"
2114
+ ],
2115
+ "parameters": [
2116
+ {
2117
+ "name": "Token",
2118
+ "in": "header",
2119
+ "required": true,
2120
+ "description": "user token",
2121
+ "schema": {
2122
+ "type": "string"
2123
+ }
2124
+ },
2125
+ {
2126
+ "name": "id",
2127
+ "in": "path",
2128
+ "required": true,
2129
+ "description": "要更新的 id",
2130
+ "schema": {
2131
+ "type": "integer"
2132
+ }
2133
+ }
2134
+ ],
2135
+ "requestBody": {
2136
+ "required": true,
2137
+ "description": "for updating a store",
2138
+ "content": {
2139
+ "multipart/form-data": {
2140
+ "schema": {
2141
+ "type": "object",
2142
+ "properties": {
2143
+ "code": {
2144
+ "type": "string",
2145
+ "description": "商店代号"
2146
+ },
2147
+ "addr": {
2148
+ "type": "string",
2149
+ "description": "对应的商店地址"
2150
+ }
2151
+ }
2152
+ }
2153
+ }
2154
+ }
2155
+ },
2156
+ "responses": {
2157
+ "200": {
2158
+ "description": "success",
2159
+ "content": {
2160
+ "application/json": {
2161
+ "schema": {
2162
+ "type": "object",
2163
+ "properties": {
2164
+ "code": {
2165
+ "type": "integer",
2166
+ "default": 200
2167
+ },
2168
+ "msg": {
2169
+ "type": "string",
2170
+ "default": "success"
2171
+ },
2172
+ "total": {
2173
+ "type": "integer"
2174
+ },
2175
+ "timestamp": {
2176
+ "type": "integer",
2177
+ "format": "time",
2178
+ "is": "time"
2179
+ },
2180
+ "language": {
2181
+ "type": "string",
2182
+ "default": "Ruby"
2183
+ },
2184
+ "data": {
2185
+ "type": "array",
2186
+ "items": {
2187
+ "type": "object"
2188
+ }
2189
+ }
2190
+ }
2191
+ }
2192
+ }
2193
+ }
2194
+ },
2195
+ "601": {
2196
+ "description": "update failed"
2197
+ },
2198
+ "-1": {
2199
+ "description": "invalid token"
2200
+ },
2201
+ "-10": {
2202
+ "description": "role verification failed"
2203
+ },
2204
+ "-11": {
2205
+ "description": "insufficient permission"
2206
+ },
2207
+ "400": {
2208
+ "description": "param validation failure"
2209
+ }
2210
+ }
2211
+ },
2212
+ "delete": {
2213
+ "summary": "Delete a Store.",
2214
+ "operationId": "destroy",
2215
+ "tags": [
2216
+ "Stores"
2217
+ ],
2218
+ "parameters": [
2219
+ {
2220
+ "name": "Token",
2221
+ "in": "header",
2222
+ "required": true,
2223
+ "description": "user token",
2224
+ "schema": {
2225
+ "type": "string"
2226
+ }
2227
+ },
2228
+ {
2229
+ "name": "id",
2230
+ "in": "path",
2231
+ "required": true,
2232
+ "description": "要删除的 id",
2233
+ "schema": {
2234
+ "type": "integer"
2235
+ }
2236
+ }
2237
+ ],
2238
+ "responses": {
2239
+ "200": {
2240
+ "description": "success",
2241
+ "content": {
2242
+ "application/json": {
2243
+ "schema": {
2244
+ "type": "object",
2245
+ "properties": {
2246
+ "code": {
2247
+ "type": "integer",
2248
+ "default": 200
2249
+ },
2250
+ "msg": {
2251
+ "type": "string",
2252
+ "default": "success"
2253
+ },
2254
+ "total": {
2255
+ "type": "integer"
2256
+ },
2257
+ "timestamp": {
2258
+ "type": "integer",
2259
+ "format": "time",
2260
+ "is": "time"
2261
+ },
2262
+ "language": {
2263
+ "type": "string",
2264
+ "default": "Ruby"
2265
+ },
2266
+ "data": {
2267
+ "type": "array",
2268
+ "items": {
2269
+ "type": "object"
2270
+ }
2271
+ }
2272
+ }
2273
+ }
2274
+ }
2275
+ }
2276
+ },
2277
+ "602": {
2278
+ "description": "destroy failed"
2279
+ },
2280
+ "-1": {
2281
+ "description": "invalid token"
2282
+ },
2283
+ "-10": {
2284
+ "description": "role verification failed"
2285
+ },
2286
+ "-11": {
2287
+ "description": "insufficient permission"
2288
+ },
2289
+ "400": {
2290
+ "description": "param validation failure"
2291
+ }
2292
+ }
2293
+ }
2294
+ },
2295
+ "/api/v1/users": {
2296
+ "get": {
2297
+ "summary": {
2298
+ "use": [
2299
+ "Token"
2300
+ ]
2301
+ },
2302
+ "operationId": "index",
2303
+ "tags": [
2304
+ "Users"
2305
+ ],
2306
+ "parameters": [
2307
+ {
2308
+ "name": "Token",
2309
+ "in": "header",
2310
+ "required": true,
2311
+ "description": "user token",
2312
+ "schema": {
2313
+ "type": "string"
2314
+ }
2315
+ },
2316
+ {
2317
+ "name": "created_start_at",
2318
+ "in": "query",
2319
+ "required": false,
2320
+ "description": "时间起点, YY-MM-DD (HH:MM:SS, 可选)",
2321
+ "schema": {
2322
+ "type": "string",
2323
+ "format": "date-time",
2324
+ "as": "start"
2325
+ }
2326
+ },
2327
+ {
2328
+ "name": "created_end_at",
2329
+ "in": "query",
2330
+ "required": false,
2331
+ "description": "时间终点, YY-MM-DD (HH:MM:SS, 可选)",
2332
+ "schema": {
2333
+ "type": "string",
2334
+ "format": "date-time",
2335
+ "as": "end"
2336
+ }
2337
+ },
2338
+ {
2339
+ "name": "page",
2340
+ "in": "query",
2341
+ "required": false,
2342
+ "description": "页数,从 1 开始",
2343
+ "schema": {
2344
+ "type": "integer",
2345
+ "minimum": 1,
2346
+ "default": 1
2347
+ }
2348
+ },
2349
+ {
2350
+ "name": "rows",
2351
+ "in": "query",
2352
+ "required": false,
2353
+ "description": "per page, 请求的数据条数",
2354
+ "schema": {
2355
+ "type": "integer",
2356
+ "minimum": 1,
2357
+ "default": 10
2358
+ }
2359
+ }
2360
+ ],
2361
+ "responses": {
2362
+ "200": {
2363
+ "description": "success",
2364
+ "content": {
2365
+ "application/json": {
2366
+ "schema": {
2367
+ "type": "object",
2368
+ "properties": {
2369
+ "code": {
2370
+ "type": "integer",
2371
+ "default": 200
2372
+ },
2373
+ "msg": {
2374
+ "type": "string",
2375
+ "default": "success"
2376
+ },
2377
+ "total": {
2378
+ "type": "integer"
2379
+ },
2380
+ "timestamp": {
2381
+ "type": "integer",
2382
+ "format": "time",
2383
+ "is": "time"
2384
+ },
2385
+ "language": {
2386
+ "type": "string",
2387
+ "default": "Ruby"
2388
+ },
2389
+ "data": {
2390
+ "type": "array",
2391
+ "items": {
2392
+ "type": "object"
2393
+ }
2394
+ }
2395
+ }
2396
+ }
2397
+ }
2398
+ }
2399
+ },
2400
+ "400": {
2401
+ "description": "param validation failure"
2402
+ }
2403
+ }
2404
+ },
2405
+ "post": {
2406
+ "summary": "register",
2407
+ "operationId": "create",
2408
+ "tags": [
2409
+ "Users"
2410
+ ],
2411
+ "parameters": [
2412
+ {
2413
+ "name": "Token",
2414
+ "in": "header",
2415
+ "required": true,
2416
+ "description": "user token",
2417
+ "schema": {
2418
+ "type": "string"
2419
+ }
2420
+ }
2421
+ ],
2422
+ "requestBody": {
2423
+ "required": true,
2424
+ "description": "register",
2425
+ "content": {
2426
+ "multipart/form-data": {
2427
+ "schema": {
2428
+ "type": "object",
2429
+ "properties": {
2430
+ "name": {
2431
+ "type": "string"
2432
+ },
2433
+ "password": {
2434
+ "type": "string"
2435
+ },
2436
+ "password_confirmation": {
2437
+ "type": "string"
2438
+ }
2439
+ },
2440
+ "required": [
2441
+ "name",
2442
+ "password",
2443
+ "password_confirmation"
2444
+ ]
2445
+ }
2446
+ }
2447
+ }
2448
+ },
2449
+ "responses": {
2450
+ "200": {
2451
+ "description": "success",
2452
+ "content": {
2453
+ "application/json": {
2454
+ "schema": {
2455
+ "type": "object",
2456
+ "properties": {
2457
+ "code": {
2458
+ "type": "integer",
2459
+ "default": 200
2460
+ },
2461
+ "msg": {
2462
+ "type": "string",
2463
+ "default": "success"
2464
+ },
2465
+ "total": {
2466
+ "type": "integer"
2467
+ },
2468
+ "timestamp": {
2469
+ "type": "integer",
2470
+ "format": "time",
2471
+ "is": "time"
2472
+ },
2473
+ "language": {
2474
+ "type": "string",
2475
+ "default": "Ruby"
2476
+ },
2477
+ "data": {
2478
+ "type": "array",
2479
+ "items": {
2480
+ "type": "object"
2481
+ }
2482
+ }
2483
+ }
2484
+ }
2485
+ }
2486
+ }
2487
+ },
2488
+ "600": {
2489
+ "description": "invalid info"
2490
+ },
2491
+ "400": {
2492
+ "description": "param validation failure"
2493
+ }
2494
+ }
2495
+ }
2496
+ },
2497
+ "/api/v1/users/{id}": {
2498
+ "get": {
2499
+ "summary": {
2500
+ "use": [
2501
+ "Token"
2502
+ ]
2503
+ },
2504
+ "operationId": "show",
2505
+ "tags": [
2506
+ "Users"
2507
+ ],
2508
+ "parameters": [
2509
+ {
2510
+ "name": "Token",
2511
+ "in": "header",
2512
+ "required": true,
2513
+ "description": "user token",
2514
+ "schema": {
2515
+ "type": "string"
2516
+ }
2517
+ },
2518
+ {
2519
+ "name": "id",
2520
+ "in": "query",
2521
+ "required": true,
2522
+ "schema": {
2523
+ "type": "integer",
2524
+ "minimum": 1
2525
+ }
2526
+ }
2527
+ ],
2528
+ "responses": {
2529
+ "200": {
2530
+ "description": "success",
2531
+ "content": {
2532
+ "application/json": {
2533
+ "schema": {
2534
+ "type": "object",
2535
+ "properties": {
2536
+ "code": {
2537
+ "type": "integer",
2538
+ "default": 200
2539
+ },
2540
+ "msg": {
2541
+ "type": "string",
2542
+ "default": "success"
2543
+ },
2544
+ "total": {
2545
+ "type": "integer"
2546
+ },
2547
+ "timestamp": {
2548
+ "type": "integer",
2549
+ "format": "time",
2550
+ "is": "time"
2551
+ },
2552
+ "language": {
2553
+ "type": "string",
2554
+ "default": "Ruby"
2555
+ },
2556
+ "data": {
2557
+ "type": "array",
2558
+ "items": {
2559
+ "type": "object"
2560
+ }
2561
+ }
2562
+ }
2563
+ }
2564
+ }
2565
+ }
2566
+ },
2567
+ "400": {
2568
+ "description": "param validation failure"
2569
+ }
2570
+ }
2571
+ }
2572
+ },
2573
+ "/api/v1/login": {
2574
+ "post": {
2575
+ "summary": "user login, and get token.",
2576
+ "operationId": "login",
2577
+ "tags": [
2578
+ "Users"
2579
+ ],
2580
+ "requestBody": {
2581
+ "required": true,
2582
+ "description": "login",
2583
+ "content": {
2584
+ "multipart/form-data": {
2585
+ "schema": {
2586
+ "type": "object",
2587
+ "properties": {
2588
+ "name": {
2589
+ "type": "string",
2590
+ "description": "user name"
2591
+ },
2592
+ "password": {
2593
+ "type": "string"
2594
+ }
2595
+ },
2596
+ "required": [
2597
+ "name",
2598
+ "password"
2599
+ ]
2600
+ }
2601
+ }
2602
+ }
2603
+ },
2604
+ "responses": {
2605
+ "200": {
2606
+ "description": "success",
2607
+ "content": {
2608
+ "application/json": {
2609
+ "schema": {
2610
+ "type": "object",
2611
+ "properties": {
2612
+ "code": {
2613
+ "type": "integer",
2614
+ "default": 200
2615
+ },
2616
+ "msg": {
2617
+ "type": "string",
2618
+ "default": "success"
2619
+ },
2620
+ "total": {
2621
+ "type": "integer"
2622
+ },
2623
+ "timestamp": {
2624
+ "type": "integer",
2625
+ "format": "time",
2626
+ "is": "time"
2627
+ },
2628
+ "language": {
2629
+ "type": "string",
2630
+ "default": "Ruby"
2631
+ },
2632
+ "data": {
2633
+ "type": "array",
2634
+ "items": {
2635
+ "type": "object"
2636
+ }
2637
+ }
2638
+ }
2639
+ }
2640
+ }
2641
+ }
2642
+ },
2643
+ "601": {
2644
+ "description": "admin not found"
2645
+ },
2646
+ "400": {
2647
+ "description": "param validation failure"
2648
+ }
2649
+ }
2650
+ }
2651
+ },
2652
+ "/api/v1/users/{id}/roles": {
2653
+ "get": {
2654
+ "summary": "GET Roles of specified user",
2655
+ "operationId": "roles",
2656
+ "tags": [
2657
+ "Users"
2658
+ ],
2659
+ "parameters": [
2660
+ {
2661
+ "name": "Token",
2662
+ "in": "header",
2663
+ "required": true,
2664
+ "description": "user token",
2665
+ "schema": {
2666
+ "type": "string"
2667
+ }
2668
+ },
2669
+ {
2670
+ "name": "id",
2671
+ "in": "path",
2672
+ "required": true,
2673
+ "description": "要查询的 user id",
2674
+ "schema": {
2675
+ "type": "integer"
2676
+ }
2677
+ }
2678
+ ],
2679
+ "responses": {
2680
+ "200": {
2681
+ "description": "success",
2682
+ "content": {
2683
+ "application/json": {
2684
+ "schema": {
2685
+ "type": "object",
2686
+ "properties": {
2687
+ "code": {
2688
+ "type": "integer",
2689
+ "default": 200
2690
+ },
2691
+ "msg": {
2692
+ "type": "string",
2693
+ "default": "success"
2694
+ },
2695
+ "total": {
2696
+ "type": "integer"
2697
+ },
2698
+ "timestamp": {
2699
+ "type": "integer",
2700
+ "format": "time",
2701
+ "is": "time"
2702
+ },
2703
+ "language": {
2704
+ "type": "string",
2705
+ "default": "Ruby"
2706
+ },
2707
+ "data": {
2708
+ "type": "array",
2709
+ "items": {
2710
+ "type": "object"
2711
+ }
2712
+ }
2713
+ }
2714
+ }
2715
+ }
2716
+ }
2717
+ },
2718
+ "400": {
2719
+ "description": "param validation failure"
2720
+ }
2721
+ }
2722
+ }
2723
+ },
2724
+ "/api/v1/users/{id}/permissions": {
2725
+ "get": {
2726
+ "summary": "GET Permissions of specified user",
2727
+ "operationId": "permissions",
2728
+ "tags": [
2729
+ "Users"
2730
+ ],
2731
+ "parameters": [
2732
+ {
2733
+ "name": "Token",
2734
+ "in": "header",
2735
+ "required": true,
2736
+ "description": "user token",
2737
+ "schema": {
2738
+ "type": "string"
2739
+ }
2740
+ },
2741
+ {
2742
+ "name": "id",
2743
+ "in": "path",
2744
+ "required": true,
2745
+ "description": "要查询的 user id",
2746
+ "schema": {
2747
+ "type": "integer"
2748
+ }
2749
+ }
2750
+ ],
2751
+ "responses": {
2752
+ "200": {
2753
+ "description": "success",
2754
+ "content": {
2755
+ "application/json": {
2756
+ "schema": {
2757
+ "type": "object",
2758
+ "properties": {
2759
+ "code": {
2760
+ "type": "integer",
2761
+ "default": 200
2762
+ },
2763
+ "msg": {
2764
+ "type": "string",
2765
+ "default": "success"
2766
+ },
2767
+ "total": {
2768
+ "type": "integer"
2769
+ },
2770
+ "timestamp": {
2771
+ "type": "integer",
2772
+ "format": "time",
2773
+ "is": "time"
2774
+ },
2775
+ "language": {
2776
+ "type": "string",
2777
+ "default": "Ruby"
2778
+ },
2779
+ "data": {
2780
+ "type": "array",
2781
+ "items": {
2782
+ "type": "object"
2783
+ }
2784
+ }
2785
+ }
2786
+ }
2787
+ }
2788
+ }
2789
+ },
2790
+ "400": {
2791
+ "description": "param validation failure"
2792
+ }
2793
+ }
2794
+ }
2795
+ },
2796
+ "/api/v1/users/{id}/roles/add": {
2797
+ "post": {
2798
+ "summary": "POST add Roles to specified user",
2799
+ "operationId": "roles_add",
2800
+ "tags": [
2801
+ "Users"
2802
+ ],
2803
+ "parameters": [
2804
+ {
2805
+ "name": "Token",
2806
+ "in": "header",
2807
+ "required": true,
2808
+ "description": "user token",
2809
+ "schema": {
2810
+ "type": "string"
2811
+ }
2812
+ },
2813
+ {
2814
+ "name": "id",
2815
+ "in": "path",
2816
+ "required": true,
2817
+ "description": "user id",
2818
+ "schema": {
2819
+ "type": "integer"
2820
+ }
2821
+ }
2822
+ ],
2823
+ "requestBody": {
2824
+ "required": true,
2825
+ "description": "for adding roles to user",
2826
+ "content": {
2827
+ "multipart/form-data": {
2828
+ "schema": {
2829
+ "type": "object",
2830
+ "properties": {
2831
+ "role_ids": {
2832
+ "type": "array",
2833
+ "items": {
2834
+ "type": "integer",
2835
+ "minimum": 1
2836
+ },
2837
+ "minLength": 1
2838
+ }
2839
+ },
2840
+ "required": [
2841
+ "role_ids"
2842
+ ]
2843
+ }
2844
+ }
2845
+ }
2846
+ },
2847
+ "responses": {
2848
+ "200": {
2849
+ "description": "success",
2850
+ "content": {
2851
+ "application/json": {
2852
+ "schema": {
2853
+ "type": "object",
2854
+ "properties": {
2855
+ "code": {
2856
+ "type": "integer",
2857
+ "default": 200
2858
+ },
2859
+ "msg": {
2860
+ "type": "string",
2861
+ "default": "success"
2862
+ },
2863
+ "total": {
2864
+ "type": "integer"
2865
+ },
2866
+ "timestamp": {
2867
+ "type": "integer",
2868
+ "format": "time",
2869
+ "is": "time"
2870
+ },
2871
+ "language": {
2872
+ "type": "string",
2873
+ "default": "Ruby"
2874
+ },
2875
+ "data": {
2876
+ "type": "array",
2877
+ "items": {
2878
+ "type": "object"
2879
+ }
2880
+ }
2881
+ }
2882
+ }
2883
+ }
2884
+ }
2885
+ },
2886
+ "400": {
2887
+ "description": "param validation failure"
2888
+ }
2889
+ }
2890
+ }
2891
+ },
2892
+ "/api/v1/users/{id}/roles/remove": {
2893
+ "post": {
2894
+ "summary": "POST remove Roles from specified user",
2895
+ "operationId": "roles_remove",
2896
+ "tags": [
2897
+ "Users"
2898
+ ],
2899
+ "parameters": [
2900
+ {
2901
+ "name": "Token",
2902
+ "in": "header",
2903
+ "required": true,
2904
+ "description": "user token",
2905
+ "schema": {
2906
+ "type": "string"
2907
+ }
2908
+ },
2909
+ {
2910
+ "name": "id",
2911
+ "in": "path",
2912
+ "required": true,
2913
+ "description": "user id",
2914
+ "schema": {
2915
+ "type": "integer"
2916
+ }
2917
+ }
2918
+ ],
2919
+ "requestBody": {
2920
+ "required": true,
2921
+ "description": "for removing roles from the user",
2922
+ "content": {
2923
+ "multipart/form-data": {
2924
+ "schema": {
2925
+ "type": "object",
2926
+ "properties": {
2927
+ "role_ids": {
2928
+ "type": "array",
2929
+ "items": {
2930
+ "type": "integer",
2931
+ "minimum": 1
2932
+ },
2933
+ "minLength": 1
2934
+ }
2935
+ },
2936
+ "required": [
2937
+ "role_ids"
2938
+ ]
2939
+ }
2940
+ }
2941
+ }
2942
+ },
2943
+ "responses": {
2944
+ "200": {
2945
+ "description": "success",
2946
+ "content": {
2947
+ "application/json": {
2948
+ "schema": {
2949
+ "type": "object",
2950
+ "properties": {
2951
+ "code": {
2952
+ "type": "integer",
2953
+ "default": 200
2954
+ },
2955
+ "msg": {
2956
+ "type": "string",
2957
+ "default": "success"
2958
+ },
2959
+ "total": {
2960
+ "type": "integer"
2961
+ },
2962
+ "timestamp": {
2963
+ "type": "integer",
2964
+ "format": "time",
2965
+ "is": "time"
2966
+ },
2967
+ "language": {
2968
+ "type": "string",
2969
+ "default": "Ruby"
2970
+ },
2971
+ "data": {
2972
+ "type": "array",
2973
+ "items": {
2974
+ "type": "object"
2975
+ }
2976
+ }
2977
+ }
2978
+ }
2979
+ }
2980
+ }
2981
+ },
2982
+ "400": {
2983
+ "description": "param validation failure"
2984
+ }
2985
+ }
2986
+ }
2987
+ }
2988
+ },
2989
+ "components": {
2990
+ "securitySchemes": {
2991
+ "ApiKeyAuth": {
2992
+ "type": "apiKey",
2993
+ "name": "server_token",
2994
+ "in": "query"
2995
+ }
2996
+ }
2997
+ }
2998
+ }