@samitouri / QOSami-HFS-2 / commits / 28d175c1

doc: improved openapi

Massimo Melina committed Apr 20, 2024 at 17:30 UTC 28d175c1cef5f2eae5454413f82268b686d2508a
1 file changed +465 -127
openapi.yaml
+465 -127
@@ -1,170 +1,477 @@
1 ----
2 -openapi: 3.0.0
1 +openapi: 3.0.1
2 info:
4 - title: HFS REST API
5 - contact:
6 - name: Massimo Melina
7 - email: a@rejetto.com
3 + title: HFS 3 HTTP API
4 + description: ''
5 version: 1.0.0
9 -servers:
10 -- url: /
6 +tags:
7 + - name: Front-end
8 paths:
9 /~/api/get_file_list:
10 get:
14 - tags:
15 - - Front-end
11 + summary: List files
12 + deprecated: false
13 description: returns all files of a specified folder
14 + tags:
15 + - Front-end
16 parameters:
18 - - name: uri
19 - in: query
20 - description: path to the folder containing the files. Default is `/`
21 - required: false
22 - style: form
23 - explode: true
24 - schema:
25 - type: string
26 - - name: offset
27 - in: query
28 - description: number of records to skip
29 - required: false
30 - style: form
31 - explode: true
32 - schema:
33 - type: number
34 - - name: limit
35 - in: query
36 - description: max number of records to return
37 - required: false
38 - style: form
39 - explode: true
40 - schema:
41 - type: number
42 - - name: search
43 - in: query
44 - description: "search for files with the specified pattern, also in subfolders."
45 - required: false
46 - style: form
47 - explode: true
48 - schema:
49 - type: string
50 - - name: c
51 - in: query
52 - description: "request separated `c` and `m` properties in entries. Pass any string to turn it on. By default only `m` is provided, and when missing it is copied from `c`."
53 - required: false
54 - style: form
55 - explode: true
56 - schema:
57 - type: string
17 + - name: uri
18 + in: query
19 + description: path to the folder containing the files. Default is `/`
20 + required: false
21 + schema:
22 + type: string
23 + - name: offset
24 + in: query
25 + description: number of records to skip
26 + required: false
27 + schema:
28 + type: number
29 + - name: limit
30 + in: query
31 + description: max number of records to return
32 + required: false
33 + schema:
34 + type: number
35 + - name: search
36 + in: query
37 + description: search for files with the specified pattern, also in subfolders.
38 + required: false
39 + schema:
40 + type: string
41 + - name: c
42 + in: query
43 + description: >-
44 + request separated `c` and `m` properties in entries. Pass any string
45 + to turn it on. By default only `m` is provided, and when missing it
46 + is copied from `c`.
47 + required: false
48 + schema:
49 + type: string
50 responses:
59 - "200":
51 + '200':
52 description: all files accordingly to the specified parameters
53 content:
54 application/json:
55 schema:
56 $ref: '#/components/schemas/inline_response_200'
57 + security: []
58 /{folder}:
59 post:
67 - tags:
68 - - Front-end
69 - summary: Uploads a file to a specific folder
60 + summary: 'Upload '
61 + deprecated: false
62 description: Equivalent to curl -F upload=@FILE FOLDER/
63 + tags:
64 + - Front-end
65 parameters:
72 - - name: folder
73 - in: path
74 - description: The folder path where the file will be uploaded
75 - required: true
76 - style: simple
77 - explode: false
78 - schema:
79 - type: string
66 + - name: folder
67 + in: path
68 + description: The folder path where the file will be uploaded
69 + required: true
70 + example: ''
71 + schema:
72 + type: string
73 + - name: x-hfs-anti-csrf
74 + in: header
75 + description: necessary only for POST requests
76 + example: '1'
77 + schema:
78 + type: string
79 + default: '1'
80 requestBody:
81 content:
82 multipart/form-data:
83 schema:
84 - $ref: '#/components/schemas/folder_body'
84 + type: object
85 + properties:
86 + file:
87 + type: string
88 + description: The file to upload.
89 + format: binary
90 encoding:
91 file:
92 contentType: application/octet-stream
88 - headers:
89 - Content-Disposition:
90 - style: simple
91 - explode: false
92 - schema:
93 - type: string
94 - description: "Form field name and filename, e.g., 'form-data; name=\"file\"; filename=\"example.txt\"'"
95 - style: form
96 - required: true
93 responses:
98 - "200":
94 + '200':
95 description: File uploaded successfully
100 - "400":
96 + content:
97 + application/json:
98 + schema:
99 + type: object
100 + properties: {}
101 + '400':
102 description: Bad request
103 + content:
104 + application/json:
105 + schema:
106 + type: object
107 + properties: {}
108 + security: []
109 + /~/api/add_account:
110 + post:
111 + summary: add account
112 + deprecated: false
113 + description: ''
114 + tags: []
115 + parameters:
116 + - name: x-hfs-anti-csrf
117 + in: header
118 + description: necessary only for POST requests
119 + example: '1'
120 + schema:
121 + type: string
122 + default: '1'
123 + requestBody:
124 + content:
125 + application/json:
126 + schema:
127 + type: object
128 + properties:
129 + username:
130 + type: string
131 + password:
132 + type: string
133 + belongs:
134 + type: array
135 + items:
136 + type: string
137 + ignore_limits:
138 + type: boolean
139 + disable_password_change:
140 + type: boolean
141 + admin:
142 + type: boolean
143 + redirect:
144 + type: string
145 + disabled:
146 + type: boolean
147 + expire: &ref_1
148 + $ref: '#/components/schemas/Date'
149 + days_to_live:
150 + type: number
151 + overwrite:
152 + type: boolean
153 + required:
154 + - username
155 + example:
156 + username: john
157 + password: betterUseLongPasswords
158 + overwrite: false
159 + responses:
160 + '200':
161 + description: Success
162 + content:
163 + application/json:
164 + schema:
165 + type: object
166 + properties: {}
167 + security: []
168 + /~/api/get_config:
169 + get:
170 + summary: get config
171 + deprecated: false
172 + description: ''
173 + tags: []
174 + parameters:
175 + - name: only
176 + in: query
177 + description: to get only specific keys from the config
178 + required: false
179 + schema:
180 + type: array
181 + items:
182 + type: string
183 + - name: omit
184 + in: query
185 + description: to get all but the specified keys from the config
186 + required: false
187 + schema:
188 + type: array
189 + items:
190 + type: string
191 + responses:
192 + '200':
193 + description: Success
194 + content:
195 + application/json:
196 + schema:
197 + type: object
198 + properties: {}
199 + security: []
200 /{folder}/{file}:
201 put:
104 - tags:
105 - - Front-end
106 - summary: Uploads a file to a specific folder
202 + summary: Upload
203 + deprecated: false
204 description: Equivalent to curl -T FILE URL/
205 + tags:
206 + - Front-end
207 parameters:
109 - - name: folder
110 - in: path
111 - description: The folder path where the file will be uploaded
112 - required: true
113 - style: simple
114 - explode: false
115 - schema:
116 - type: string
117 - - name: file
118 - in: path
119 - description: The uploaded file name
120 - required: true
121 - style: simple
122 - explode: false
123 - schema:
124 - type: string
208 + - name: folder
209 + in: path
210 + description: The folder path where the file will be uploaded
211 + required: true
212 + example: ''
213 + schema:
214 + type: string
215 + - name: file
216 + in: path
217 + description: The uploaded file name
218 + required: true
219 + example: ''
220 + schema:
221 + type: string
222 requestBody:
223 content:
127 - application/octet-stream: {}
128 - required: true
224 + application/octet-stream:
225 + schema:
226 + type: string
227 + format: binary
228 responses:
130 - "200":
229 + '200':
230 description: File uploaded successfully
231 + content:
232 + application/json:
233 + schema:
234 + type: object
235 + properties: {}
236 + security: []
237 + /~/api/set_account:
238 + post:
239 + summary: update account
240 + deprecated: false
241 + description: ''
242 + tags: []
243 + parameters:
244 + - name: x-hfs-anti-csrf
245 + in: header
246 + description: necessary only for POST requests
247 + example: '1'
248 + schema:
249 + type: string
250 + default: '1'
251 + requestBody:
252 + content:
253 + application/json:
254 + schema:
255 + type: object
256 + properties:
257 + username:
258 + type: string
259 + changes: &ref_0
260 + $ref: '#/components/schemas/Account'
261 + required:
262 + - username
263 + - changes
264 + example:
265 + username: john
266 + password: betterUseLongPasswords
267 + overwrite: false
268 + responses:
269 + '200':
270 + description: Success
271 + content:
272 + application/json:
273 + schema:
274 + type: object
275 + properties: {}
276 + security: []
277 + /~/api/set_config:
278 + post:
279 + summary: set config
280 + deprecated: false
281 + description: ''
282 + tags: []
283 + parameters:
284 + - name: x-hfs-anti-csrf
285 + in: header
286 + description: necessary only for POST requests
287 + example: '1'
288 + schema:
289 + type: string
290 + default: '1'
291 + requestBody:
292 + content:
293 + application/json:
294 + schema:
295 + type: object
296 + properties:
297 + values:
298 + type: object
299 + properties: {}
300 + required:
301 + - 01HVXZ10SH9AHVGST5XV79TK5A
302 + description: all keys are the defined in config.md file
303 + required:
304 + - values
305 + responses:
306 + '200':
307 + description: Success
308 + content:
309 + application/json:
310 + schema:
311 + type: object
312 + properties: {}
313 + security: []
314 + /~/api/del_account:
315 + post:
316 + summary: delete account
317 + deprecated: false
318 + description: ''
319 + tags: []
320 + parameters:
321 + - name: x-hfs-anti-csrf
322 + in: header
323 + description: necessary only for POST requests
324 + example: '1'
325 + schema:
326 + type: string
327 + default: '1'
328 + requestBody:
329 + content:
330 + application/json:
331 + schema:
332 + type: object
333 + properties:
334 + username:
335 + type: string
336 + required:
337 + - username
338 + example:
339 + username: john
340 + password: betterUseLongPasswords
341 + overwrite: false
342 + responses:
343 + '200':
344 + description: Success
345 + content:
346 + application/json:
347 + schema:
348 + type: object
349 + properties: {}
350 + security: []
351 + /~/api/get_accounts:
352 + get:
353 + summary: list accounts
354 + deprecated: false
355 + description: ''
356 + tags: []
357 + parameters: []
358 + responses:
359 + '200':
360 + description: Success
361 + content:
362 + application/json:
363 + schema:
364 + type: object
365 + properties:
366 + list:
367 + type: array
368 + items: *ref_0
369 + required:
370 + - list
371 + security: []
372 + /~/api/get_usernames:
373 + get:
374 + summary: list usernames
375 + deprecated: false
376 + description: ''
377 + tags: []
378 + parameters: []
379 + responses:
380 + '200':
381 + description: Success
382 + content:
383 + application/json:
384 + schema:
385 + type: object
386 + properties:
387 + list:
388 + type: array
389 + items:
390 + type: string
391 + required:
392 + - list
393 + security: []
394 + /~/api/get_admins:
395 + get:
396 + summary: list admins
397 + deprecated: false
398 + description: ''
399 + tags: []
400 + parameters: []
401 + responses:
402 + '200':
403 + description: Success
404 + content:
405 + application/json:
406 + schema:
407 + type: object
408 + properties:
409 + list:
410 + type: array
411 + items:
412 + type: string
413 + description: username
414 + required:
415 + - list
416 + security: []
417 + /~/api/get_account:
418 + get:
419 + summary: get account
420 + deprecated: false
421 + description: you can also call this with POST
422 + tags: []
423 + parameters:
424 + - name: username
425 + in: query
426 + description: ''
427 + required: false
428 + schema:
429 + type: string
430 + responses:
431 + '200':
432 + description: Success
433 + content:
434 + application/json:
435 + schema: *ref_0
436 + security: []
437 components:
438 schemas:
134 - DirEntry:
135 - required:
136 - - "n"
439 + Date:
440 + type: string
441 + format: date-time
442 + Account:
443 type: object
444 properties:
139 - "n":
445 + username:
446 type: string
141 - description: name of the entry. Can be a relative path in case you used `search`.
142 - c:
447 + password:
448 type: string
144 - description: creation time
145 - format: date-time
146 - m:
449 + belongs:
450 + type: array
451 + items:
452 + type: string
453 + ignore_limits:
454 + type: boolean
455 + disable_password_change:
456 + type: boolean
457 + admin:
458 + type: boolean
459 + redirect:
460 type: string
148 - description: modification time
149 - format: date-time
150 - s:
461 + disabled:
462 + type: boolean
463 + expire: *ref_1
464 + days_to_live:
465 type: number
152 - description: "size, in bytes"
153 - p:
154 - pattern: "[rR]?[lL]?d?"
155 - type: string
156 - description: |
157 - permissions, only when are different from the parent folder.
158 - Meaning of each character:
159 - - r: cannot be downloaded
160 - - R: can be downloaded only with other credentials
161 - - l: folder cannot be listed
162 - - L: folder can be listed only with other credetnials
163 - - d: can be deleted
164 - comment:
466 + required:
467 + - username
468 + folder_body:
469 + type: object
470 + properties:
471 + file:
472 type: string
166 - description: assigned comment
167 - description: front-end list item format. Common properties are kept short to optimize space.
473 + description: The file to upload.
474 + format: binary
475 inline_response_200:
476 type: object
477 properties:
@@ -185,10 +492,41 @@ components:
492 description: entries from this folder
493 items:
494 $ref: '#/components/schemas/DirEntry'
188 - folder_body:
495 + DirEntry:
496 + required:
497 + - 'n'
498 type: object
499 properties:
191 - file:
500 + 'n':
501 type: string
193 - description: The file to upload.
194 - format: binary
502 + description: name of the entry. Can be a relative path in case you used `search`.
503 + c:
504 + type: string
505 + description: creation time
506 + format: date-time
507 + m:
508 + type: string
509 + description: modification time
510 + format: date-time
511 + s:
512 + type: number
513 + description: size, in bytes
514 + p:
515 + pattern: '[rR]?[lL]?d?'
516 + type: string
517 + description: |
518 + permissions, only when are different from the parent folder.
519 + Meaning of each character:
520 + - r: cannot be downloaded
521 + - R: can be downloaded only with other credentials
522 + - l: folder cannot be listed
523 + - L: folder can be listed only with other credetnials
524 + - d: can be deleted
525 + comment:
526 + type: string
527 + description: assigned comment
528 + description: >-
529 + front-end list item format. Common properties are kept short to optimize
530 + space.
531 + securitySchemes: {}
532 +servers: []