Skip to content

Commit 0ef310d

Browse files
sledgehammer999sledgehammer999
committed
WebAPI: Document API using OpenAPI
This is simply a demo.
1 parent 1e27e65 commit 0ef310d

File tree

3 files changed

+314
-0
lines changed

3 files changed

+314
-0
lines changed

‎src/webui/openapi/authcontroller.yml

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
login:
2+
post:
3+
summary: Login
4+
description: Login and get SID cookie
5+
security: [ ]
6+
requestBody:
7+
required: true
8+
content:
9+
application/x-www-form-urlencoded:
10+
schema:
11+
type: object
12+
properties:
13+
username:
14+
type: string
15+
password:
16+
type: string
17+
required: ['username', 'password']
18+
responses:
19+
'200':
20+
description: Login success or failure based on the response string. If login succeeded, the authorization cookie will be set. The cookie name might be configured to a different name by the user.
21+
headers:
22+
SID:
23+
required: false
24+
content:
25+
text/plain; charset=UTF-8:
26+
schema:
27+
oneOf:
28+
- type: string
29+
const: 'Ok.'
30+
- type: string
31+
const: 'Fails.'
32+
'403':
33+
$ref: 'main.yml#/components/responses/403forbidden'
34+
logout:
35+
get:
36+
summary: Logout
37+
description: Logout and unset auth cookie. The cookie name might be configured to a different name by the user.
38+
responses:
39+
'200':
40+
description: OK
41+
headers:
42+
SID:
43+
required: false

‎src/webui/openapi/main.yml

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
openapi: '3.1.0'
2+
info:
3+
description: This is the specification for qBittorrent's web API
4+
title: qBittorrent WebAPI
5+
version: '2.11.2'
6+
servers:
7+
- url: 'https://localhost:{port}/api/v2'
8+
variables:
9+
port:
10+
default: "8080"
11+
components:
12+
securitySchemes:
13+
defaultApiKey:
14+
description: API key cookie provided when logged in successfully. The cookie name might be configured to a different name by the user.
15+
type: apiKey
16+
name: SID
17+
in: cookie
18+
responses:
19+
200simpleOK:
20+
description: OK
21+
200TextOK:
22+
description: OK
23+
content:
24+
text/plain; charset=UTF-8:
25+
schema:
26+
type: string
27+
400badRequest:
28+
description: Bad Request
29+
content:
30+
text/plain; charset=UTF-8:
31+
schema:
32+
type: string
33+
401unauthorized:
34+
description: Unauthorized
35+
content:
36+
text/plain; charset=UTF-8:
37+
schema:
38+
type: string
39+
403forbidden:
40+
description: Forbidden
41+
content:
42+
text/plain; charset=UTF-8:
43+
schema:
44+
type: string
45+
404notFound:
46+
description: Not Found
47+
content:
48+
text/plain; charset=UTF-8:
49+
schema:
50+
type: string
51+
405methodNotAllowed:
52+
description: Method Not Allowed
53+
content:
54+
text/plain; charset=UTF-8:
55+
schema:
56+
type: string
57+
409conflict:
58+
description: Conflict
59+
content:
60+
text/plain; charset=UTF-8:
61+
schema:
62+
type: string
63+
415unsupportedMediaType:
64+
description: Unsupported Media Type
65+
content:
66+
text/plain; charset=UTF-8:
67+
schema:
68+
type: string
69+
500internalServerError:
70+
description: Internal Server Error
71+
content:
72+
text/plain; charset=UTF-8:
73+
schema:
74+
type: string
75+
security:
76+
- defaultApiKey: []
77+
paths:
78+
/transfer/info:
79+
$ref: 'transfercontroller.yml#/info'
80+
/transfer/uploadLimit:
81+
$ref: 'transfercontroller.yml#/uploadLimit'
82+
/transfer/downloadLimit:
83+
$ref: 'transfercontroller.yml#/downloadLimit'
84+
/transfer/setUploadLimit:
85+
$ref: 'transfercontroller.yml#/setUploadLimit'
86+
/transfer/setDownloadLimit:
87+
$ref: 'transfercontroller.yml#/setDownloadLimit'
88+
/transfer/toggleSpeedLimitsMode:
89+
$ref: 'transfercontroller.yml#/toggleSpeedLimitsMode'
90+
/transfer/speedLimitsMode:
91+
$ref: 'transfercontroller.yml#/speedLimitsMode'
92+
/transfer/setSpeedLimitsMode:
93+
$ref: 'transfercontroller.yml#/setSpeedLimitsMode'
94+
/transfer/banPeers:
95+
$ref: 'transfercontroller.yml#/banPeers'
96+
/auth/login:
97+
$ref: 'authcontroller.yml#/login'
98+
/auth/logout:
99+
$ref: 'authcontroller.yml#/logout'

‎src/webui/openapi/transfercontroller.yml

+172
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
info:
2+
get:
3+
summary: Get the global transfer information
4+
responses:
5+
'200':
6+
description: OK
7+
content:
8+
application/json:
9+
schema:
10+
type: object
11+
properties:
12+
dl_info_speed:
13+
description: Global download rate in bytes per second
14+
type: number
15+
dl_info_data:
16+
description: Data downloaded this session in bytes
17+
type: number
18+
dl_rate_limit:
19+
description: Download rate limit in bytes per second
20+
type: number
21+
up_info_speed:
22+
description: Global upload rate in bytes per second
23+
type: number
24+
up_info_data:
25+
description: Data uploaded this session in bytes
26+
type: number
27+
up_rate_limit:
28+
description: Upload rate limit in bytes per second
29+
type: number
30+
dht_nodes:
31+
description: Number of DHT nodes connected to
32+
type: number
33+
connection_status:
34+
description: Connection status
35+
type: string
36+
enum:
37+
- connected
38+
- firewalled
39+
- disconnected
40+
required:
41+
- 'dl_info_speed'
42+
- 'dl_info_data'
43+
- 'dl_rate_limit'
44+
- 'up_info_speed'
45+
- 'up_info_data'
46+
- 'up_rate_limit'
47+
- 'dht_nodes'
48+
- 'connection_status'
49+
'403':
50+
$ref: 'main.yml#/components/responses/403forbidden'
51+
uploadLimit:
52+
get:
53+
summary: Get upload speed limit
54+
responses:
55+
'200':
56+
$ref: 'main.yml#/components/responses/200TextOK'
57+
'403':
58+
$ref: 'main.yml#/components/responses/403forbidden'
59+
downloadLimit:
60+
get:
61+
summary: Get download speed limit
62+
responses:
63+
'200':
64+
$ref: 'main.yml#/components/responses/200TextOK'
65+
'403':
66+
$ref: 'main.yml#/components/responses/403forbidden'
67+
setUploadLimit:
68+
post:
69+
summary: Set upload speed limit
70+
requestBody:
71+
required: true
72+
content:
73+
application/x-www-form-urlencoded:
74+
schema:
75+
type: object
76+
properties:
77+
limit:
78+
description: Speed limit in bytes per second. Negative values disable the limit. Non-negative values below 1024 are clamped to 1024.
79+
type: number
80+
required: ['limit']
81+
responses:
82+
'200':
83+
$ref: 'main.yml#/components/responses/200simpleOK'
84+
'403':
85+
$ref: 'main.yml#/components/responses/403forbidden'
86+
setDownloadLimit:
87+
post:
88+
summary: Set download speed limit
89+
requestBody:
90+
required: true
91+
content:
92+
application/x-www-form-urlencoded:
93+
schema:
94+
type: object
95+
properties:
96+
limit:
97+
description: Speed limit in bytes per second. Negative values disable the limit. Non-negative values below 1024 are clamped to 1024.
98+
type: number
99+
required: ['limit']
100+
responses:
101+
'200':
102+
$ref: 'main.yml#/components/responses/200simpleOK'
103+
'403':
104+
$ref: 'main.yml#/components/responses/403forbidden'
105+
toggleSpeedLimitsMode:
106+
post:
107+
summary: Toggle speed limit mode
108+
description: Toggle speed limit mode between normal and alternative
109+
responses:
110+
'200':
111+
$ref: 'main.yml#/components/responses/200simpleOK'
112+
'403':
113+
$ref: 'main.yml#/components/responses/403forbidden'
114+
speedLimitsMode:
115+
get:
116+
summary: Get speed limit mode
117+
description: '`1` means alternative mode and `0` normal mode'
118+
responses:
119+
'200':
120+
description: OK
121+
content:
122+
text/plain; charset=UTF-8:
123+
schema:
124+
type: number
125+
enum:
126+
- 0
127+
- 1
128+
'403':
129+
$ref: 'main.yml#/components/responses/403forbidden'
130+
setSpeedLimitsMode:
131+
post:
132+
summary: Set speed limit mode
133+
requestBody:
134+
required: true
135+
content:
136+
application/x-www-form-urlencoded:
137+
schema:
138+
type: object
139+
properties:
140+
mode:
141+
description: '`1` means alternative mode and `0` normal mode.'
142+
type: number
143+
enum:
144+
- 0
145+
- 1
146+
required: ['mode']
147+
responses:
148+
'200':
149+
$ref: 'main.yml#/components/responses/200simpleOK'
150+
'400':
151+
$ref: 'main.yml#/components/responses/400badRequest'
152+
'403':
153+
$ref: 'main.yml#/components/responses/403forbidden'
154+
banPeers:
155+
post:
156+
summary: Ban peers
157+
requestBody:
158+
required: true
159+
content:
160+
application/x-www-form-urlencoded:
161+
schema:
162+
type: object
163+
properties:
164+
peers:
165+
description: List of peer IPs to ban. Each list item is separated by the `|` character.
166+
type: string
167+
required: ['peers']
168+
responses:
169+
'200':
170+
$ref: 'main.yml#/components/responses/200simpleOK'
171+
'403':
172+
$ref: 'main.yml#/components/responses/403forbidden'

0 commit comments

Comments
 (0)