From 22b46686398f6e7a1b0e9514737bcd02f84b0853 Mon Sep 17 00:00:00 2001 From: Rick van Lieshout Date: Tue, 25 Jun 2024 09:46:45 +0200 Subject: [PATCH] docs: updated swagger docs for player and legacy --- src/features/api/features/player.ts | 81 ++++++--- src/features/api/legacy.ts | 96 +++++++++++ src/features/api/swagger.json | 255 ++++++++++++++++++++++++---- src/pages/settings/settings.html | 4 +- src/preload.ts | 6 +- 5 files changed, 380 insertions(+), 62 deletions(-) diff --git a/src/features/api/features/player.ts b/src/features/api/features/player.ts index dd0722c..64f9fed 100644 --- a/src/features/api/features/player.ts +++ b/src/features/api/features/player.ts @@ -29,12 +29,13 @@ export const addPlaybackControl = (expressApp: Router, mainWindow: BrowserWindow if (settingsStore.get(settings.playBackControl)) { /** * @swagger - * /play: - * get: - * summary: Play action + * /player/play: + * post: + * summary: Play the current media + * tags: [player] * responses: * 200: - * description: Action performed + * description: Ok * content: * text/plain: * schema: @@ -44,12 +45,13 @@ export const addPlaybackControl = (expressApp: Router, mainWindow: BrowserWindow /** * @swagger - * /favorite/toggle: + * /player/favorite/toggle: * post: - * summary: Toggle favorite + * summary: Add the current media to your favorites, or remove it if its already added to your favorites + * tags: [player] * responses: * 200: - * description: Action performed + * description: Ok * content: * text/plain: * schema: @@ -59,12 +61,13 @@ export const addPlaybackControl = (expressApp: Router, mainWindow: BrowserWindow /** * @swagger - * /pause: - * get: - * summary: Pause action + * /player/pause: + * post: + * summary: Pause the current media + * tags: [player] * responses: * 200: - * description: Action performed + * description: Ok * content: * text/plain: * schema: @@ -74,12 +77,13 @@ export const addPlaybackControl = (expressApp: Router, mainWindow: BrowserWindow /** * @swagger - * /next: - * get: - * summary: Next action + * /player/next: + * post: + * summary: Play the next song + * tags: [player] * responses: * 200: - * description: Action performed + * description: Ok * content: * text/plain: * schema: @@ -89,12 +93,13 @@ export const addPlaybackControl = (expressApp: Router, mainWindow: BrowserWindow /** * @swagger - * /previous: - * get: - * summary: Previous action + * /player/previous: + * post: + * summary: Play the previous song + * tags: [player] * responses: * 200: - * description: Action performed + * description: Ok * content: * text/plain: * schema: @@ -102,17 +107,47 @@ export const addPlaybackControl = (expressApp: Router, mainWindow: BrowserWindow */ createPlayerAction("/previous", globalEvents.previous); + /** + * @swagger + * /player/shuffle/toggle: + * post: + * summary: Play the previous song + * tags: [player] + * responses: + * 200: + * description: Ok + * content: + * text/plain: + * schema: + * $ref: '#/components/schemas/OkResponse' + */ createPlayerAction("/shuffle/toggle", globalEvents.toggleShuffle); + + /** + * @swagger + * /player/repeat/toggle: + * post: + * summary: Toggle the repeat status, toggles between "off" , "single" and "all" + * tags: [player] + * responses: + * 200: + * description: Ok + * content: + * text/plain: + * schema: + * $ref: '#/components/schemas/OkResponse' + */ createPlayerAction("/repeat/toggle", globalEvents.toggleRepeat); /** * @swagger - * /playpause: - * get: - * summary: Toggle play/pause + * /player/playpause: + * post: + * summary: Start playing the media if paused, or pause the media if playing + * tags: [player] * responses: * 200: - * description: Action performed + * description: Ok * content: * text/plain: * schema: diff --git a/src/features/api/legacy.ts b/src/features/api/legacy.ts index 6c73db1..fdec402 100644 --- a/src/features/api/legacy.ts +++ b/src/features/api/legacy.ts @@ -18,6 +18,7 @@ export const addLegacyApi = (expressApp: Router, mainWindow: BrowserWindow) => { * /image: * get: * summary: Get current image + * tags: [legacy] * deprecated: true * responses: * 200: @@ -36,13 +37,108 @@ export const addLegacyApi = (expressApp: Router, mainWindow: BrowserWindow) => { addLegacyControls(); } function addLegacyControls() { + /** + * @swagger + * /play: + * get: + * summary: Play the current media + * tags: [legacy] + * deprecated: true + * responses: + * 200: + * description: Action performed + * content: + * text/plain: + * schema: + * $ref: '#/components/schemas/OkResponse' + */ expressApp.get("/play", ({ res }) => handleGlobalEvent(res, globalEvents.play)); + + /** + * @swagger + * /favorite/toggle: + * get: + * summary: Add the current media to your favorites, or remove it if its already added to your favorites + * tags: [legacy] + * deprecated: true + * responses: + * 200: + * description: Ok + * content: + * text/plain: + * schema: + * $ref: '#/components/schemas/OkResponse' + */ expressApp.post("/favorite/toggle", (req, res) => handleGlobalEvent(res, globalEvents.toggleFavorite) ); + + /** + * @swagger + * /pause: + * get: + * summary: Pause the current media + * tags: [legacy] + * deprecated: true + * responses: + * 200: + * description: Ok + * content: + * text/plain: + * schema: + * $ref: '#/components/schemas/OkResponse' + */ expressApp.get("/pause", (req, res) => handleGlobalEvent(res, globalEvents.pause)); + + /** + * @swagger + * /next: + * get: + * summary: Play the next song + * tags: [legacy] + * deprecated: true + * responses: + * 200: + * description: Ok + * content: + * text/plain: + * schema: + * $ref: '#/components/schemas/OkResponse' + */ expressApp.get("/next", (req, res) => handleGlobalEvent(res, globalEvents.next)); + + /** + * @swagger + * /previous: + * get: + * summary: Play the previous song + * tags: [legacy] + * deprecated: true + * responses: + * 200: + * description: Ok + * content: + * text/plain: + * schema: + * $ref: '#/components/schemas/OkResponse' + */ expressApp.get("/previous", (req, res) => handleGlobalEvent(res, globalEvents.previous)); + + /** + * @swagger + * /playpause: + * get: + * summary: Toggle play/pause + * tags: [legacy] + * deprecated: true + * responses: + * 200: + * description: Ok + * content: + * text/plain: + * schema: + * $ref: '#/components/schemas/OkResponse' + */ expressApp.get("/playpause", (req, res) => { if (mediaInfo.status === MediaStatus.playing) { handleGlobalEvent(res, globalEvents.pause); diff --git a/src/features/api/swagger.json b/src/features/api/swagger.json index 8c49f5f..0b655a0 100644 --- a/src/features/api/swagger.json +++ b/src/features/api/swagger.json @@ -62,29 +62,15 @@ } } }, - "/play": { - "get": { - "summary": "Play action", - "responses": { - "200": { - "description": "Action performed", - "content": { - "text/plain": { - "schema": { - "$ref": "#/components/schemas/OkResponse" - } - } - } - } - } - } - }, - "/favorite/toggle": { + "/player/play": { "post": { - "summary": "Toggle favorite", + "summary": "Play action", + "tags": [ + "player" + ], "responses": { "200": { - "description": "Action performed", + "description": "Ok", "content": { "text/plain": { "schema": { @@ -96,12 +82,35 @@ } } }, - "/pause": { - "get": { + "/player/favorite/toggle": { + "post": { + "summary": "Add the current song to your favorites, or remove it if its already added to your favorites", + "tags": [ + "player" + ], + "responses": { + "200": { + "description": "Ok", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/OkResponse" + } + } + } + } + } + } + }, + "/player/pause": { + "post": { "summary": "Pause action", + "tags": [ + "player" + ], "responses": { "200": { - "description": "Action performed", + "description": "Ok", "content": { "text/plain": { "schema": { @@ -113,12 +122,15 @@ } } }, - "/next": { - "get": { - "summary": "Next action", + "/player/next": { + "post": { + "summary": "Play the next song", + "tags": [ + "player" + ], "responses": { "200": { - "description": "Action performed", + "description": "Ok", "content": { "text/plain": { "schema": { @@ -130,12 +142,35 @@ } } }, - "/previous": { - "get": { + "/player/previous": { + "post": { + "summary": "Play the previous song", + "tags": [ + "player" + ], + "responses": { + "200": { + "description": "Ok", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/OkResponse" + } + } + } + } + } + } + }, + "/player/shuffle/toggle": { + "post": { "summary": "Previous action", + "tags": [ + "player" + ], "responses": { "200": { - "description": "Action performed", + "description": "Ok", "content": { "text/plain": { "schema": { @@ -147,12 +182,35 @@ } } }, - "/playpause": { - "get": { - "summary": "Toggle play/pause", + "/player/repeat/toggle": { + "post": { + "summary": "Toggle the repeat status, toggles between \"off\" , \"single\" and \"all\"", + "tags": [ + "player" + ], "responses": { "200": { - "description": "Action performed", + "description": "Ok", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/OkResponse" + } + } + } + } + } + } + }, + "/player/playpause": { + "post": { + "summary": "Toggle play/pause", + "tags": [ + "player" + ], + "responses": { + "200": { + "description": "Ok", "content": { "text/plain": { "schema": { @@ -255,6 +313,9 @@ "/image": { "get": { "summary": "Get current image", + "tags": [ + "legacy" + ], "deprecated": true, "responses": { "200": { @@ -273,6 +334,132 @@ } } } + }, + "/play": { + "get": { + "summary": "Play action", + "tags": [ + "legacy" + ], + "deprecated": true, + "responses": { + "200": { + "description": "Action performed", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/OkResponse" + } + } + } + } + } + } + }, + "/favorite/toggle": { + "get": { + "summary": "Add the current song to your favorites, or remove it if its already added to your favorites", + "tags": [ + "legacy" + ], + "deprecated": true, + "responses": { + "200": { + "description": "Ok", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/OkResponse" + } + } + } + } + } + } + }, + "/pause": { + "get": { + "summary": "Pause action", + "tags": [ + "legacy" + ], + "deprecated": true, + "responses": { + "200": { + "description": "Ok", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/OkResponse" + } + } + } + } + } + } + }, + "/next": { + "get": { + "summary": "Play the next song", + "tags": [ + "legacy" + ], + "deprecated": true, + "responses": { + "200": { + "description": "Ok", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/OkResponse" + } + } + } + } + } + } + }, + "/previous": { + "get": { + "summary": "Play the previous song", + "tags": [ + "legacy" + ], + "deprecated": true, + "responses": { + "200": { + "description": "Ok", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/OkResponse" + } + } + } + } + } + } + }, + "/playpause": { + "get": { + "summary": "Toggle play/pause", + "tags": [ + "legacy" + ], + "deprecated": true, + "responses": { + "200": { + "description": "Ok", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/OkResponse" + } + } + } + } + } + } } }, "components": { diff --git a/src/pages/settings/settings.html b/src/pages/settings/settings.html index a39aa58..e697580 100644 --- a/src/pages/settings/settings.html +++ b/src/pages/settings/settings.html @@ -147,7 +147,7 @@

API

- TIDAL Hi-Fi has a built-in web API to allow users to get current song information. + TIDAL Hi-Fi has a built-in web API to allow users to get current media information. You can optionally enable playback control as well.

@@ -246,7 +246,7 @@

Show song

-

Show the current song in the Discord client

+

Show the current media in the Discord client