From 5cb9a7e8cfef2212711753aa8887fc495345ab2b Mon Sep 17 00:00:00 2001 From: Manuel Raimo Date: Sun, 22 Oct 2023 21:01:37 +0200 Subject: [PATCH] docs: added openapi specification for the new api --- .github/workflows/mkdocs.yml | 2 +- docs/api.md | 2 + docs/index.md | 2 +- docs/openapi.json | 622 +++++++++++++++++++++++++++++++++++ mkdocs.yml | 6 +- 5 files changed, 630 insertions(+), 4 deletions(-) create mode 100644 docs/api.md create mode 100644 docs/openapi.json diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml index 3833cc1..5b62618 100644 --- a/.github/workflows/mkdocs.yml +++ b/.github/workflows/mkdocs.yml @@ -21,5 +21,5 @@ jobs: path: .cache restore-keys: | mkdocs-material- - - run: pip install mkdocs-material + - run: pip install mkdocs-material mkdocs-render-swagger-plugin - run: mkdocs gh-deploy --force diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..cf8c5fc --- /dev/null +++ b/docs/api.md @@ -0,0 +1,2 @@ +# API Reference +!!swagger openapi.json!! \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 80b2283..49870bc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ Yet Another Discord Music Bot - A music bot written in go - Supports what [yt-dlp](https://github.com/yt-dlp/yt-dlp) supports, plus spotify playlists (if you configure the required tokens!) -- Uses slash commands (see [Commands](commands) for a list of commands) +- Uses slash commands (see [Commands](commands.md) for a list of commands) - Save your favorite songs and playlists with custom commands - Automatically skips sponsors or moments when there's no music, thanks to the [SponsorBlock API](https://sponsor.ajay.app/) diff --git a/docs/openapi.json b/docs/openapi.json new file mode 100644 index 0000000..5e31d10 --- /dev/null +++ b/docs/openapi.json @@ -0,0 +1,622 @@ +{ + "openapi": "3.0.0", + "info": { + "version": "1.0.0", + "title": "YADMB", + "description": "The web api for interacting with the music bot" + }, + "tags": [ + { + "name": "favorites", + "description": "Manage and see the user's favorites" + }, + { + "name": "queue", + "description": "Manage the server's queue" + }, + { + "name": "song", + "description": "Play/pause the current song" + } + ], + "paths": { + "/favorites": { + "get": { + "tags": [ + "favorites" + ], + "summary": "Get favorites", + "description": "Returns all the favorite for the given user", + "parameters": [ + { + "name": "token", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "Token for authentication" + } + ], + "operationId": "getFavorites", + "responses": { + "200": { + "description": "All the favorites of the user", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/Favorite1" + }, + { + "$ref": "#/components/schemas/Favorite2" + }, + { + "$ref": "#/components/schemas/Favorite3" + } + ] + } + } + } + } + }, + "401": { + "description": "Token not valid" + } + } + }, + "post": { + "tags": [ + "favorites" + ], + "summary": "Add a favorite", + "description": "Adds a favorite to the database", + "parameters": [ + { + "name": "name", + "in": "header", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 100 + }, + "description": "The name of the favorite, max 100 characters" + }, + { + "name": "link", + "in": "header", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 200 + }, + "description": "The link of the song, max 200 characters" + }, + { + "name": "folder", + "in": "header", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 100 + }, + "description": "The name of the folder" + }, + { + "name": "token", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "Token for authentication" + } + ], + "operationId": "addFavorite", + "responses": { + "200": { + "description": "Favorite added successfully" + }, + "401": { + "description": "Token not valid" + }, + "500": { + "description": "Name duplicated for the given user" + } + } + }, + "delete": { + "tags": [ + "favorites" + ], + "summary": "Remove a favorite", + "description": "Removes a favorite from the database", + "parameters": [ + { + "name": "name", + "in": "header", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 100 + }, + "description": "The name of the favorite" + }, + { + "name": "token", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "Token for authentication" + } + ], + "operationId": "removeFavorite", + "responses": { + "200": { + "description": "Favorite removed successfully" + }, + "401": { + "description": "Token not valid" + }, + "500": { + "description": "Favorite doesn't exist" + } + } + } + }, + "/queue/{guild}": { + "get": { + "tags": [ + "queue" + ], + "summary": "Get the entire queue for a given guild", + "description": "Returns the entire queue of a guild", + "parameters": [ + { + "name": "guild", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The guild id" + }, + { + "name": "token", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "Token for authentication" + } + ], + "operationId": "getQueue", + "responses": { + "200": { + "description": "Elements of the queue", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/Element1" + }, + { + "$ref": "#/components/schemas/Element2" + } + ] + } + } + } + } + }, + "401": { + "description": "Token not valid or it doesn't have access to the given guild" + } + } + }, + "post": { + "tags": [ + "queue" + ], + "summary": "Add a song to the queue", + "description": "Adds the given song to the queue", + "parameters": [ + { + "name": "guild", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The guild id" + }, + { + "name": "song", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "A link to a song or a query to search on youtube" + }, + { + "name": "playlist", + "in": "header", + "required": false, + "schema": { + "type": "string", + "default": "false" + }, + "description": "Is the song a playlist?" + }, + { + "name": "shuffle", + "in": "header", + "required": false, + "schema": { + "type": "string", + "default": "false" + }, + "description": "Should we shuffle the given playlist?" + }, + { + "name": "loop", + "in": "header", + "required": false, + "schema": { + "type": "string", + "default": "false" + }, + "description": "Should the song be looped?" + }, + { + "name": "priority", + "in": "header", + "required": false, + "schema": { + "type": "string", + "default": "false" + }, + "description": "Should we add the song as the first in the queue?" + }, + { + "name": "token", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "Token for authentication" + } + ], + "operationId": "addToQueue", + "responses": { + "200": { + "description": "Song added successfully" + }, + "401": { + "description": "Token not valid or it doesn't have access to the given guild" + } + } + }, + "delete": { + "tags": [ + "queue" + ], + "summary": "Skip the currently playing song", + "description": "Skip the currently playing song", + "parameters": [ + { + "name": "guild", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The guild id" + } + ], + "operationId": "skip", + "responses": { + "200": { + "description": "Song skipped successfully" + }, + "401": { + "description": "Token not valid or it doesn't have access to the given guild" + } + } + } + }, + "/song/pause/{guild}": { + "get": { + "tags": [ + "song" + ], + "summary": "Pause the currently playing song", + "description": "Pause the currently playing song", + "parameters": [ + { + "name": "guild", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The guild id" + }, + { + "name": "token", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "Token for authentication" + } + ], + "operationId": "pause", + "responses": { + "200": { + "description": "Song paused successfully" + }, + "401": { + "description": "Token not valid or it doesn't have access to the given guild" + }, + "406": { + "description": "Song is already paused" + } + } + } + }, + "/song/resume/{guild}": { + "get": { + "tags": [ + "song" + ], + "summary": "Resume the currently playing song", + "description": "Resume the currently playing song", + "parameters": [ + { + "name": "guild", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The guild id" + }, + { + "name": "token", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "Token for authentication" + } + ], + "operationId": "resume", + "responses": { + "200": { + "description": "Song resumed successfully" + }, + "401": { + "description": "Token not valid or it doesn't have access to the given guild" + }, + "406": { + "description": "Song is already playing" + } + } + } + }, + "/song/toggle/{guild}": { + "get": { + "tags": [ + "song" + ], + "summary": "Play/pauses the currently playing song", + "description": "Play/pauses the currently playing song", + "parameters": [ + { + "name": "guild", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The guild id" + }, + { + "name": "token", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "Token for authentication" + } + ], + "operationId": "toggle", + "responses": { + "200": { + "description": "Song paused or resumed successfully" + }, + "401": { + "description": "Token not valid or it doesn't have access to the given guild" + }, + "500": { + "description": "Couldn't toggle song" + } + } + } + } + }, + "components": { + "schemas": { + "Element1": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "KygYQJEi3SQ-youtube" + }, + "title": { + "type": "string", + "example": "Charlie - Faccia da Pirla" + }, + "duration": { + "type": "string", + "example": "04:19" + }, + "link": { + "type": "string", + "example": "https://www.youtube.com/watch?v=KygYQJEi3SQ" + }, + "user": { + "type": "string", + "example": "thetipo01" + }, + "thumbnail": { + "type": "string", + "example": "https://i.ytimg.com/vi/KygYQJEi3SQ/maxresdefault.jpg" + }, + "loop": { + "type": "boolean", + "example": false + }, + "frames": { + "type": "integer", + "example": 10248 + } + }, + "required": [ + "id", + "title", + "duration", + "link", + "user", + "thumbnail", + "loop" + ] + }, + "Element2": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "PvuYSybooLg-youtube" + }, + "title": { + "type": "string", + "example": "Lights, Camera, Action! - Studiopolis Zone Act 1" + }, + "duration": { + "type": "string", + "example": "03:08" + }, + "link": { + "type": "string", + "example": "https://www.youtube.com/watch?v=PvuYSybooLg" + }, + "user": { + "type": "string", + "example": "thetipo01" + }, + "thumbnail": { + "type": "string", + "example": "https://i.ytimg.com/vi/PvuYSybooLg/maxresdefault.jpg" + }, + "loop": { + "type": "boolean", + "example": false + } + }, + "required": [ + "id", + "title", + "duration", + "link", + "user", + "thumbnail", + "loop" + ] + }, + "Favorite1": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "Very nice song" + }, + "link": { + "type": "string", + "example": "https://www.youtube.com/watch?v=PvuYSybooLg" + }, + "folder": { + "type": "string", + "example": "Sonic OST" + } + }, + "required": [ + "name", + "link" + ] + }, + "Favorite2": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "The Top" + }, + "link": { + "type": "string", + "example": "https://www.youtube.com/watch?v=6wftUIvoHAQ" + }, + "folder": { + "type": "string", + "example": "Eurobeat" + } + }, + "required": [ + "name", + "link" + ] + }, + "Favorite3": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "Blue Jeans" + }, + "link": { + "type": "string", + "example": "https://www.youtube.com/watch?v=4MKAf6YX_7M" + }, + "folder": { + "type": "string", + "example": "" + } + }, + "required": [ + "name", + "link" + ] + } + } + } +} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 133cc12..0d6e074 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,10 @@ site_name: YADMB +site_description: Yet Another Discord Music Bot - A music bot written in go + theme: name: material - -site_description: Yet Another Discord Music Bot - A music bot written in go +plugins: + - render_swagger # Repository repo_name: TheTipo01/YADMB