From 3e77ff11e50068666a301302267d7a386e6e91f8 Mon Sep 17 00:00:00 2001
From: sledgehammer999 <hammered999@gmail.com>
Date: Sun, 10 Nov 2024 21:38:16 +0200
Subject: [PATCH] WebAPI: Document API using OpenAPI

This is simply a demo.
---
 src/webui/openapi/main.yml | 185 +++++++++++++++++++++++++++++++++++++
 1 file changed, 185 insertions(+)
 create mode 100644 src/webui/openapi/main.yml

diff --git a/src/webui/openapi/main.yml b/src/webui/openapi/main.yml
new file mode 100644
index 000000000000..7b65bfd33da6
--- /dev/null
+++ b/src/webui/openapi/main.yml
@@ -0,0 +1,185 @@
+openapi: '3.1.0'
+info:
+  description: This is the specification for qBittorrent's web API
+  title: qBittorrent WebAPI
+  version: '2.11.2'
+servers:
+  - url: 'https://localhost:{port}/api/v2'
+    variables:
+      port:
+        default: "8080"
+components:
+  securitySchemes:
+    defaultApiKey:
+      description: API key cookie provided when logged in successfully.
+      type: apiKey
+      name: SID
+      in: cookie
+security:
+  - defaultApiKey: []
+paths:
+  /transfer/info:
+    post:
+      summary: Returns the global transfer information in JSON format.
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  dl_info_speed:
+                    description: Global download rate in bytes per second
+                    type: number
+                  dl_info_data:
+                    description: Data downloaded this session in bytes
+                    type: number
+                  dl_rate_limit:
+                    description: Download rate limit in bytes per second
+                    type: number
+                  up_info_speed:
+                    description: Global upload rate in bytes per second
+                    type: number
+                  up_info_data:
+                    description: Data uploaded this session in bytes
+                    type: number
+                  up_rate_limit:
+                    description: Upload rate limit in bytes per second
+                    type: number
+                  dht_nodes:
+                    description: Number of DHT nodes connected to
+                    type: number
+                  connection_status:
+                    description: Connection status
+                    type: string
+                    enum:
+                    - connected
+                    - firewalled
+                    - disconnected
+                required:
+                  - 'dl_info_speed'
+                  - 'dl_info_data'
+                  - 'dl_rate_limit'
+                  - 'up_info_speed'
+                  - 'up_info_data'
+                  - 'up_rate_limit'
+                  - 'dht_nodes'
+                  - 'connection_status'
+  /transfer/uploadLimit:
+    get:
+      summary: Get upload speed limit.
+      responses:
+        '200':
+          description: OK
+          content:
+            text/plain; charset=UTF-8:
+              schema:
+                type: string
+  /transfer/downloadLimit:
+    get:
+      summary: Get download speed limit.
+      responses:
+        '200':
+          description: OK
+          content:
+            text/plain; charset=UTF-8:
+              schema:
+                type: string
+  /transfer/setUploadLimit:
+    post:
+      summary: Get upload speed limit.
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                limit:
+                  description: Speed limit in bytes per second. Negative values disable the limit. Non-negative values below 1024 are clamped to 1024.
+                  type: number
+              required: ['limit']
+      responses:
+        '200':
+          description: OK
+  /transfer/setDownloadLimit:
+    post:
+      summary: Get download speed limit.
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                limit:
+                  description: Speed limit in bytes per second. Negative values disable the limit. Non-negative values below 1024 are clamped to 1024.
+                  type: number
+              required: ['limit']
+      responses:
+        '200':
+          description: OK
+  /transfer/toggleSpeedLimitsMode:
+    get:
+      summary: Toggle speed limit mode between normal and alternative.
+      responses:
+        '200':
+          description: OK
+  /transfer/speedLimitsMode:
+    get:
+      summary: Get speed limit mode. `1` means alternative mode and `0` normal mode.
+      responses:
+        '200':
+          description: OK
+          content:
+            text/plain; charset=UTF-8:
+              schema:
+                type: number
+                enum:
+                    - 0
+                    - 1
+  /transfer/setSpeedLimitsMode:
+    post:
+      summary: Set speed limit mode.
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                mode:
+                  description: '`1` means alternative mode and `0` normal mode.'
+                  type: number
+                  enum:
+                    - 0
+                    - 1
+              required: ['mode']
+      responses:
+        '200':
+          description: OK
+        '400':
+          description: Bad Request
+          content:
+            text/plain; charset=UTF-8:
+              schema:
+                type: string
+                const: "'mode': invalid argument"
+  /transfer/banPeers:
+      post:
+        summary: Ban peers.
+        requestBody:
+          required: true
+          content:
+            application/x-www-form-urlencoded:
+              schema:
+                type: object
+                properties:
+                  peers:
+                    description: List of peer IPs to ban. Each list item is separated by the `|` character.
+                    type: string
+                required: ['peers']
+        responses:
+          '200':
+            description: OK