doc: improved openapi
Massimo Melina committed
Apr 23, 2024 at 16:04 UTC
848c45918f0794aef1b921e06c2e3ba3904bff2b
2 files changed
+61
-14
dev-plugins.md
+3
-3
@@ -43,11 +43,11 @@ Let's first look at the things you can export:
43
44
All the following properties are optional unless otherwise specified.
45
46
-- `description: string` try to explain what this plugin is for.
46
+- `description: string` try to explain what this plugin is for. (JSON syntax)
47
- `version: number` use progressive numbers to distinguish each release
48
- `apiRequired: number | [min:number,max:number]` declare version(s) for which the plugin is designed for. Mandatory. [Refer to API version history](#api-version-history)
49
-- `depend: { repo: string, version: number }[]` declare what other plugins this depends on.
50
-- `repo: string | object` pointer to a GitHub repo where this plugin is hosted.
49
+- `depend: { repo: string, version: number }[]` declare what other plugins this depends on. (JSON syntax)
50
+- `repo: string | object` pointer to a GitHub repo where this plugin is hosted. (JSON syntax)
51
- the string form is for GitHub repos. Example: "rejetto/file-icons"
52
- the object form will point to other custom repo. Object properties:
53
- `web: string` link to a web page
openapi.yaml
+58
-11
@@ -1,6 +1,6 @@
1
openapi: 3.0.1
2
info:
3
- title: HFS 3 HTTP API
3
+ title: HFS 3
4
description: ''
5
version: 1.0.0
6
tags:
@@ -163,7 +163,12 @@ paths:
163
application/json:
164
schema:
165
type: object
166
- properties: {}
166
+ properties:
167
+ username:
168
+ type: string
169
+ description: returned because it is normalized
170
+ required:
171
+ - username
172
security: []
173
/~/api/get_config:
174
get:
@@ -261,10 +266,7 @@ paths:
266
required:
267
- username
268
- changes
264
- example:
265
- username: john
266
- password: betterUseLongPasswords
267
- overwrite: false
269
+ example: ''
270
responses:
271
'200':
272
description: Success
@@ -272,7 +274,12 @@ paths:
274
application/json:
275
schema:
276
type: object
275
- properties: {}
277
+ properties:
278
+ username:
279
+ type: string
280
+ description: returned because it is normalized
281
+ required:
282
+ - username
283
security: []
284
/~/api/set_config:
285
post:
@@ -335,10 +342,50 @@ paths:
342
type: string
343
required:
344
- username
338
- example:
339
- username: john
340
- password: betterUseLongPasswords
341
- overwrite: false
345
+ example: ''
346
+ responses:
347
+ '200':
348
+ description: Success
349
+ content:
350
+ application/json:
351
+ schema:
352
+ type: object
353
+ properties: {}
354
+ security: []
355
+ /~/api/change_srp:
356
+ post:
357
+ summary: safer update of the password
358
+ deprecated: false
359
+ description: >-
360
+ use SRP protocol to change the password without transmitting it. If your
361
+ channel is trusted, you can just specify 'password' in set_account or
362
+ add_account, that's much simpler.
363
+ tags: []
364
+ parameters:
365
+ - name: x-hfs-anti-csrf
366
+ in: header
367
+ description: necessary only for POST requests
368
+ example: '1'
369
+ schema:
370
+ type: string
371
+ default: '1'
372
+ requestBody:
373
+ content:
374
+ application/json:
375
+ schema:
376
+ type: object
377
+ properties:
378
+ username:
379
+ type: string
380
+ salt:
381
+ type: string
382
+ verifier:
383
+ type: string
384
+ required:
385
+ - username
386
+ - salt
387
+ - verifier
388
+ example: ''
389
responses:
390
'200':
391
description: Success