From 3f8cc735fa7e04aebb3da7c7e18632d648f24e11 Mon Sep 17 00:00:00 2001
From: Valentin Sickert <17144397+Lapotor@users.noreply.github.com>
Date: Sun, 26 Nov 2023 01:59:51 +0100
Subject: [PATCH] chore(docs): add `swagger.yml` for api reference

Signed-off-by: Valentin Sickert <17144397+Lapotor@users.noreply.github.com>
---
 .github/assets/swagger,yml | 762 +++++++++++++++++++++++++++++++++++++
 1 file changed, 762 insertions(+)
 create mode 100644 .github/assets/swagger,yml

diff --git a/.github/assets/swagger,yml b/.github/assets/swagger,yml
new file mode 100644
index 00000000..454d5013
--- /dev/null
+++ b/.github/assets/swagger,yml
@@ -0,0 +1,762 @@
+swagger: "2.0"
+info:
+    title: RadioSchedule API
+    description: API for the broadcast schedule
+    version: 1.0.0
+    license:
+        name: AGPL-3.0
+        url: https://github.com/Lapotor/RadioRoster-api/blob/main/LICENSE
+schemes:
+    - https
+consumes:
+    - application/json
+produces:
+    - application/json
+paths:
+    /shows:
+        get:
+            tags:
+                - Shows
+            summary: "Returns the broadcast schedule for a specified time period."
+            operationId: getSchedule
+            produces:
+                - application/json
+            parameters:
+                - in: query
+                  name: start_date
+                  description: "Start date of the broadcast schedule."
+                  type: string
+                  format: date-time
+                - in: query
+                  name: end_date
+                  description: "End date of the broadcast schedule."
+                  type: string
+                  format: date-time
+                - in: query
+                  name: days
+                  description: "Number of days for which to return the broadcast schedule."
+                  type: integer
+                  maximum: 30
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        type: array
+                        items:
+                            $ref: "#/definitions/Show"
+                "500":
+                    $ref: "#/responses/500"
+        post:
+            tags:
+                - Shows
+            summary: "Creates a new show."
+            operationId: createShow
+            security:
+                - BearerAuth: []
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            parameters:
+                - in: body
+                  name: show
+                  description: "The details of the new show to create."
+                  schema:
+                      $ref: "#/definitions/Show"
+            responses:
+                "201":
+                    description: "CREATED"
+                    schema:
+                        $ref: "#/definitions/Show"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "500":
+                    $ref: "#/responses/500"
+
+    /shows/{id}:
+        get:
+            tags:
+                - Shows
+            summary: "Retrieves a show by ID."
+            operationId: getShow
+            produces:
+                - application/json
+            parameters:
+                - in: path
+                  name: id
+                  description: "The ID of the show to retrieve."
+                  type: integer
+                  required: true
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        $ref: "#/definitions/Show"
+                "400":
+                    $ref: "#/responses/400"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+        patch:
+            tags:
+                - Shows
+            summary: "Updates an existing show by ID."
+            operationId: updateShow
+            security:
+                - BearerAuth: []
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            parameters:
+                - name: id
+                  in: path
+                  description: "The ID of the show to update."
+                  type: integer
+                  required: true
+                - name: show
+                  in: body
+                  description: "The updated details of the show."
+                  schema:
+                      $ref: "#/definitions/Show"
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        $ref: "#/definitions/Show"
+                "400":
+                    $ref: "#/responses/400"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+        delete:
+            tags:
+                - Shows
+            summary: "Deletes a show by ID."
+            operationId: deleteShow
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: id
+                  description: "The ID of the show to delete."
+                  type: integer
+                  required: true
+            responses:
+                "204":
+                    description: "NO CONTENT"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+
+    /requests:
+        get:
+            tags:
+                - Requests
+            summary: "Retrieves the wishbox requests."
+            operationId: getRequests
+            security:
+                - BearerAuth: []
+            produces:
+                - application/json
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        type: array
+                        items:
+                            $ref: "#/definitions/Request"
+                "500":
+                    $ref: "#/responses/500"
+        post:
+            tags:
+                - Requests
+            summary: "Sends a request to the radio station's wishbox."
+            operationId: sendRequest
+            security:
+                - BearerAuth: []
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            parameters:
+                - in: body
+                  name: request
+                  description: "Information about the wish request."
+                  schema:
+                      $ref: "#/definitions/Request"
+            responses:
+                "201":
+                    description: "CREATED"
+                    schema:
+                        $ref: "#/definitions/Request"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "500":
+                    $ref: "#/responses/500"
+
+    /requests/{id}:
+        delete:
+            tags:
+                - Requests
+            summary: "Deletes a specific wishlist request by ID."
+            operationId: deleteRequest
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: id
+                  in: path
+                  description: "The ID of the wishbox request to delete."
+                  type: integer
+                  required: true
+            responses:
+                "204":
+                    description: "NO CONTENT"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+
+    /users:
+        get:
+            tags:
+                - User
+            summary: "Returns a list of all registered users."
+            operationId: getUsers
+            security:
+                - BearerAuth: []
+            produces:
+                - application/json
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        type: array
+                        items:
+                            $ref: "#/definitions/User"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "500":
+                    $ref: "#/responses/500"
+        post:
+            tags:
+                - User
+            summary: "Creates a new user."
+            operationId: createUser
+            security:
+                - BearerAuth: []
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            parameters:
+                - in: body
+                  name: user
+                  description: "User object that needs to be added."
+                  schema:
+                      $ref: "#/definitions/User"
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        $ref: "#/definitions/User"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "500":
+                    $ref: "#/responses/500"
+
+    /users/{id}:
+        get:
+            tags:
+                - User
+            summary: "Gets a user by ID."
+            operationId: getUser
+            security:
+                - BearerAuth: []
+            produces:
+                - application/json
+            parameters:
+                - in: path
+                  name: id
+                  type: integer
+                  description: "The ID of the user to retrieve."
+                  required: true
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        $ref: "#/definitions/User"
+                "400":
+                    $ref: "#/responses/400"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+        patch:
+            tags:
+                - User
+            summary: "Updates a user by ID."
+            operationId: updateUser
+            security:
+                - BearerAuth: []
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            parameters:
+                - name: id
+                  in: path
+                  description: "The ID of the user to update."
+                  type: integer
+                  required: true
+                - name: user
+                  in: body
+                  description: "The updated user information."
+                  required: true
+                  schema:
+                      $ref: "#/definitions/User"
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        $ref: "#/definitions/User"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+        delete:
+            tags:
+                - User
+            summary: "Deletes a user by ID."
+            operationId: deleteUser
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: id
+                  in: path
+                  description: "The ID of the user to delete."
+                  type: integer
+                  required: true
+            responses:
+                "204":
+                    description: "NO CONTENT"
+                "400":
+                    $ref: "#/responses/400"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+
+    /roles:
+        get:
+            tags:
+                - Role
+            summary: "Retrieves all availble roles"
+            operationId: getAllRoles
+            security:
+                - BearerAuth: []
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        type: array
+                        items:
+                            $ref: "#/definitions/Role"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+        post:
+            tags:
+                - Role
+            summary: "Add a role"
+            operationId: createRole
+            security:
+                - BearerAuth: []
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            parameters:
+                - in: body
+                  name: Role data
+                  description: "The data for the role which should be added"
+                  schema:
+                      $ref: "#/definitions/Role"
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        $ref: "#/definitions/Role"
+                "400":
+                    $ref: "#/responses/400"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "500":
+                    $ref: "#/responses/500"
+
+    /roles/{id}:
+        get:
+            tags:
+                - Role
+            summary: "Retrieves a roles"
+            operationId: getRole
+            security:
+                - BearerAuth: []
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            parameters:
+                - in: path
+                  name: id
+                  required: true
+                  type: integer
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        $ref: "#/definitions/Role"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+        patch:
+            tags:
+                - Role
+            summary: "Update a role"
+            operationId: updateRole
+            security:
+                - BearerAuth: []
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            parameters:
+                - in: path
+                  name: id
+                  required: true
+                  type: integer
+                - in: body
+                  name: changes
+                  required: true
+                  schema:
+                      $ref: "#/definitions/Role"
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        $ref: "#/definitions/Role"
+                "400":
+                    $ref: "#/responses/400"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+        delete:
+            tags:
+                - Role
+            summary: "Deletes a role"
+            operationId: deleteRole
+            security:
+                - BearerAuth: []
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            parameters:
+                - in: path
+                  name: id
+                  required: true
+                  type: integer
+            responses:
+                "204":
+                    description: "NO CONTENT"
+                "401":
+                    $ref: "#/responses/401"
+                "403":
+                    $ref: "#/responses/403"
+                "404":
+                    $ref: "#/responses/404"
+                "500":
+                    $ref: "#/responses/500"
+
+    /login:
+        post:
+            tags:
+                - Auth
+            summary: "Logs in a user and returns a JWT-Token."
+            operationId: login
+            consumes:
+                - application/json
+            produces:
+                - application/json
+            parameters:
+                - in: body
+                  name: credentials
+                  description: "The user's login information."
+                  schema:
+                      type: object
+                      properties:
+                          username:
+                              type: string
+                          password:
+                              type: string
+                      required:
+                          - username
+                          - password
+            responses:
+                "200":
+                    description: "OK"
+                    schema:
+                        type: object
+                        properties:
+                            access_token:
+                                type: string
+                "500":
+                    $ref: "#/responses/500"
+
+    /logout:
+        post:
+            tags:
+                - Auth
+            summary: "Logs out the current user."
+            operationId: logout
+            security:
+                - BearerAuth: []
+            produces:
+                - application/json
+            responses:
+                "204":
+                    description: "NO CONTENT"
+                "401":
+                    $ref: "#/responses/401"
+                "500":
+                    $ref: "#/responses/500"
+
+securityDefinitions:
+    BearerAuth:
+        type: apiKey
+        name: Authorization
+        in: header
+        description: >-
+            Enter the token with the `Bearer: ` prefix, e.g. "Bearer abcde12345".
+
+definitions:
+    Show:
+        type: object
+        required:
+            - id
+            - created_at
+            - updated_at
+            - title
+            - start_date
+            - end_date
+            - is_live
+            - enabled
+            - moderators
+        properties:
+            id:
+                type: integer
+            created_at:
+                type: string
+                format: date-time
+            updated_at:
+                type: string
+                format: date-time
+            title:
+                type: string
+            body:
+                type: object
+            start_date:
+                type: string
+                format: date-time
+            end_date:
+                type: string
+                format: date-time
+            is_live:
+                type: boolean
+            enabled:
+                type: boolean
+            moderators:
+                type: array
+                minItems: 1
+                items:
+                    type: object
+                    properties:
+                        id:
+                            type: integer
+                        name:
+                            type: string
+                        primary:
+                            type: boolean
+            locked_by:
+                type: integer
+
+    Request:
+        type: object
+        required:
+            - id
+            - name
+            - message
+            - created_at
+        properties:
+            id:
+                type: integer
+            name:
+                type: string
+            message:
+                type: string
+            created_at:
+                type: string
+                format: date-time
+
+    User:
+        type: object
+        required:
+            - id
+            - created_at
+            - updated_at
+            - name
+            - email
+            - password
+        properties:
+            id:
+                type: integer
+            created_at:
+                type: string
+                format: date-time
+            updated_at:
+                type: string
+                format: date-time
+            name:
+                type: string
+            email:
+                type: string
+            email_verified_at:
+                type: string
+                format: date-time
+            password:
+                type: string
+                format: password
+            role:
+                type: integer
+
+    Role:
+        type: object
+        required:
+            - id
+            - created_at
+            - updated_at
+            - name
+            - permissions
+        properties:
+            id:
+                type: integer
+            created_at:
+                type: string
+                format: date-time
+            updated_at:
+                type: string
+                format: date-time
+            name:
+                type: string
+            permissions:
+                type: object
+
+    Error:
+        type: object
+        properties:
+            error:
+                type: string
+                example: "Not Found"
+            status:
+                type: integer
+                example: 404
+            message:
+                type: string
+                example: "The server cannot find the requested resource."
+
+responses:
+    400:
+        description: >-
+            Bad Request - The server cannot or will not process the request due to an apparent client error.
+        schema:
+            $ref: "#/definitions/Error"
+
+    401:
+        description: >-
+            Unauthorized - The request requires authentication or the user has not been authenticated.
+        schema:
+            $ref: "#/definitions/Error"
+
+    403:
+        description: >-
+            Forbidden - The server understood the request, but is refusing to fulfill it.
+        schema:
+            $ref: "#/definitions/Error"
+
+    404:
+        description: >-
+            Not Found - The server cannot find the requested resource.
+        schema:
+            $ref: "#/definitions/Error"
+
+    500:
+        description: >-
+            Internal Server Error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
+        schema:
+            $ref: "#/definitions/Error"