apiRoutesDoc.yaml

openapi: 3.0.0
servers:
  - description: API Simpsons Trivia server
    url: https://simpsons-trivia.onrender.com/triviasimpsons/api/v1
  - description: API Simpsons Trivia localhost
    url: http://localhost:3001/triviasimpsons/api/v1

info:
  description: This is a simple API of Simpsons Trivia
  version: "1.2"
  title: Simple API Simpsons Trivia
  contact:
    email: tomas.saintromain@gmail.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
  - name: Public
    description: Publicly accessible endpoints
  - name: Authentication
    description: User authentication and registration
  - name: Admin
    description: Secured Admin-only calls

paths:
  /:
    get:
      tags:
        - Public
      summary: Welcome message
      operationId: welcomeMessage
      description: Display a welcome message for the Simpsons Trivia API.
      responses:
        '200':
          description: Welcome message
          content:
            text/html:
              schema:
                type: string
                example: "Welcome to the Simpsons Trivia API..."

  /healthcheck:
    get:
      tags:
        - Public
      summary: Health check
      operationId: healthCheck
      description: Check the health status of the API.
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  timestamp:
                    type: string
                    format: date-time

  /users:
    get:
      tags:
        - Admin
      summary: Get users list
      operationId: getUsersList
      description: Retrieve information about all users (Admin only).
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved user information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        username:
                          type: string
                        role:
                          type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /scores:
    get:
      tags:
        - Admin
      summary: Get user scores
      operationId: getUsersScores
      description: Retrieve user scores (Admin only).
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved user scores
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        score:
                          type: integer
                        username:
                          type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /quote/questions:
    get:
      tags:
        - Public
      summary: Get trivia questions
      operationId: getQuestionsTrivia
      description: Retrieve a list of trivia questions.
      responses:
        '200':
          description: Successfully retrieved trivia questions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        quote:
                          type: string
                        data:
                          type: string

  /quote/random:
    get:
      tags:
        - Public
      summary: Get a random quote with 4 answers
      operationId: getQuote
      description: Retrieve a random quote with 4 possible answers.
      responses:
        '200':
          description: Successfully retrieved a random quote
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      quote:
                        type: string
                      options:
                        type: array
                        items:
                          type: string

  /quotes/bycharacter/{characterId}:
    get:
      tags:
        - Public
      summary: Get quotes by character
      operationId: getQuotesByCharacter
      description: Retrieve quotes for a specific character.
      parameters:
        - in: path
          name: characterId
          required: true
          schema:
            type: integer
          description: The ID of the character
      responses:
        '200':
          description: Successfully retrieved quotes for the character
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      character:
                        type: string
                      totalQuotes:
                        type: integer
                      quotes:
                        type: object
                        additionalProperties:
                          type: object
                          properties:
                            id:
                              type: integer
                            quote:
                              type: string
        '400':
          description: Invalid character ID
        '404':
          description: Character not found or no quotes available

  /characters:
    get:
      tags:
        - Public
      summary: Get characters
      operationId: getCharacters
      description: Retrieve a list of Simpsons characters.
      responses:
        '200':
          description: Successfully retrieved characters
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
        '404':
          description: No characters found

  /login:
    post:
      tags:
        - Authentication
      summary: Login user
      operationId: loginUserReq
      description: Login with a created user account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: The email of the user.
                password:
                  type: string
                  description: The account password.
              required:
                - email
                - password
      responses:
        '200':
          description: User successfully logged in
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  token:
                    type: string
                  user:
                    type: object
                    properties:
                      id:
                        type: integer
                      username:
                        type: string
                      role:
                        type: string
        '400':
          description: Invalid input
        '409':
          description: Login failed

  /register:
    post:
      tags:
        - Authentication
      summary: Register user
      operationId: registerUserReq
      description: Register a new user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Email to register.
                username:
                  type: string
                  description: Username for the account.
                password:
                  type: string
                  description: Create a password.
              required:
                - email
                - username
                - password
      responses:
        '200':
          description: User successfully registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  user:
                    type: object
                    properties:
                      id:
                        type: integer
                      username:
                        type: string
                      role:
                        type: string
        '400':
          description: Invalid input
        '409':
          description: Email already exists

  /users/{userId}/role:
    patch:
      tags:
        - Admin
      summary: Change user role
      operationId: changeUserRole
      description: Change the role of a specific user (Admin only).
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: integer
          description: The ID of the user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                newRole:
                  type: string
                  description: The new role to assign to the user.
              required:
                - newRole
      responses:
        '200':
          description: User role successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  user:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      email:
                        type: string
                      previousRole:
                        type: string
                      newRole:
                        type: string
        '400':
          description: Invalid input
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: User not found

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    UnauthorizedError:
      description: Access token is missing or invalid
    ForbiddenError:
      description: The server understood the request but refuses to authorize it