From 0ef310d6f116d2573ac214b656f186eebe247d65 Mon Sep 17 00:00:00 2001 From: sledgehammer999 Date: Sun, 10 Nov 2024 21:38:16 +0200 Subject: [PATCH] WebAPI: Document API using OpenAPI This is simply a demo. --- src/webui/openapi/authcontroller.yml | 43 ++++++ src/webui/openapi/main.yml | 99 +++++++++++++ src/webui/openapi/transfercontroller.yml | 172 +++++++++++++++++++++++ 3 files changed, 314 insertions(+) create mode 100644 src/webui/openapi/authcontroller.yml create mode 100644 src/webui/openapi/main.yml create mode 100644 src/webui/openapi/transfercontroller.yml diff --git a/src/webui/openapi/authcontroller.yml b/src/webui/openapi/authcontroller.yml new file mode 100644 index 00000000000..632c8aa1fbe --- /dev/null +++ b/src/webui/openapi/authcontroller.yml @@ -0,0 +1,43 @@ +login: + post: + summary: Login + description: Login and get SID cookie + security: [ ] + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + properties: + username: + type: string + password: + type: string + required: ['username', 'password'] + responses: + '200': + 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. + headers: + SID: + required: false + content: + text/plain; charset=UTF-8: + schema: + oneOf: + - type: string + const: 'Ok.' + - type: string + const: 'Fails.' + '403': + $ref: 'main.yml#/components/responses/403forbidden' +logout: + get: + summary: Logout + description: Logout and unset auth cookie. The cookie name might be configured to a different name by the user. + responses: + '200': + description: OK + headers: + SID: + required: false diff --git a/src/webui/openapi/main.yml b/src/webui/openapi/main.yml new file mode 100644 index 00000000000..4bfce03420e --- /dev/null +++ b/src/webui/openapi/main.yml @@ -0,0 +1,99 @@ +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. The cookie name might be configured to a different name by the user. + type: apiKey + name: SID + in: cookie + responses: + 200simpleOK: + description: OK + 200TextOK: + description: OK + content: + text/plain; charset=UTF-8: + schema: + type: string + 400badRequest: + description: Bad Request + content: + text/plain; charset=UTF-8: + schema: + type: string + 401unauthorized: + description: Unauthorized + content: + text/plain; charset=UTF-8: + schema: + type: string + 403forbidden: + description: Forbidden + content: + text/plain; charset=UTF-8: + schema: + type: string + 404notFound: + description: Not Found + content: + text/plain; charset=UTF-8: + schema: + type: string + 405methodNotAllowed: + description: Method Not Allowed + content: + text/plain; charset=UTF-8: + schema: + type: string + 409conflict: + description: Conflict + content: + text/plain; charset=UTF-8: + schema: + type: string + 415unsupportedMediaType: + description: Unsupported Media Type + content: + text/plain; charset=UTF-8: + schema: + type: string + 500internalServerError: + description: Internal Server Error + content: + text/plain; charset=UTF-8: + schema: + type: string +security: + - defaultApiKey: [] +paths: + /transfer/info: + $ref: 'transfercontroller.yml#/info' + /transfer/uploadLimit: + $ref: 'transfercontroller.yml#/uploadLimit' + /transfer/downloadLimit: + $ref: 'transfercontroller.yml#/downloadLimit' + /transfer/setUploadLimit: + $ref: 'transfercontroller.yml#/setUploadLimit' + /transfer/setDownloadLimit: + $ref: 'transfercontroller.yml#/setDownloadLimit' + /transfer/toggleSpeedLimitsMode: + $ref: 'transfercontroller.yml#/toggleSpeedLimitsMode' + /transfer/speedLimitsMode: + $ref: 'transfercontroller.yml#/speedLimitsMode' + /transfer/setSpeedLimitsMode: + $ref: 'transfercontroller.yml#/setSpeedLimitsMode' + /transfer/banPeers: + $ref: 'transfercontroller.yml#/banPeers' + /auth/login: + $ref: 'authcontroller.yml#/login' + /auth/logout: + $ref: 'authcontroller.yml#/logout' diff --git a/src/webui/openapi/transfercontroller.yml b/src/webui/openapi/transfercontroller.yml new file mode 100644 index 00000000000..b34ad8528dd --- /dev/null +++ b/src/webui/openapi/transfercontroller.yml @@ -0,0 +1,172 @@ +info: + get: + summary: Get the global transfer information + 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' + '403': + $ref: 'main.yml#/components/responses/403forbidden' +uploadLimit: + get: + summary: Get upload speed limit + responses: + '200': + $ref: 'main.yml#/components/responses/200TextOK' + '403': + $ref: 'main.yml#/components/responses/403forbidden' +downloadLimit: + get: + summary: Get download speed limit + responses: + '200': + $ref: 'main.yml#/components/responses/200TextOK' + '403': + $ref: 'main.yml#/components/responses/403forbidden' +setUploadLimit: + post: + summary: Set 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': + $ref: 'main.yml#/components/responses/200simpleOK' + '403': + $ref: 'main.yml#/components/responses/403forbidden' +setDownloadLimit: + post: + summary: Set 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': + $ref: 'main.yml#/components/responses/200simpleOK' + '403': + $ref: 'main.yml#/components/responses/403forbidden' +toggleSpeedLimitsMode: + post: + summary: Toggle speed limit mode + description: Toggle speed limit mode between normal and alternative + responses: + '200': + $ref: 'main.yml#/components/responses/200simpleOK' + '403': + $ref: 'main.yml#/components/responses/403forbidden' +speedLimitsMode: + get: + summary: Get speed limit mode + description: '`1` means alternative mode and `0` normal mode' + responses: + '200': + description: OK + content: + text/plain; charset=UTF-8: + schema: + type: number + enum: + - 0 + - 1 + '403': + $ref: 'main.yml#/components/responses/403forbidden' +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': + $ref: 'main.yml#/components/responses/200simpleOK' + '400': + $ref: 'main.yml#/components/responses/400badRequest' + '403': + $ref: 'main.yml#/components/responses/403forbidden' +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': + $ref: 'main.yml#/components/responses/200simpleOK' + '403': + $ref: 'main.yml#/components/responses/403forbidden'