swagger.yaml

openapi: 3.0.0
info:
  title: FinanzApp API
  description: API Documentation for FinanzApp
  version: 1.0.0
servers:
  - url: http://localhost:3000/api/v1
    description: Local server

tags:
  - name: Users
    description: Operations related to users
  - name: Budgets Configurations
    description: Operations related to budget configurations
  - name: Budgets
    description: Operations related to budgets

paths:
  /users:
    get:
      tags:
        - Users
      summary: Get all users
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Users not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

    post:
      tags:
        - Users
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostUser'
      responses:
        '201':
          description: User created successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /budgets/{id}:
    get:
      tags:
        - Budgets
      summary: Get a budget by ID
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Budget found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetDetails'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Budget not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /budget-configurations:
    get:
      tags:
        - Budgets Configurations
      summary: Retrieve budget configurations
      description: Returns an array of budget configurations, filtered by optional query parameters.
      parameters:
        - $ref: '#/components/parameters/GetBudgetConfigurationsFilters'
      responses:
        '200':
          description: A list of budget configurations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BudgetConfigurationWithBudgets'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Internal server error'
    post:
      tags:
        - Budgets Configurations
      summary: Create a new budget configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostBudgetConfiguration'
      responses:
        '201':
          description: Budget configuration created successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /budget-configurations/{id}:
    patch:
      tags:
        - Budgets Configurations
      summary: Partially update a budget configuration
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the budget configuration to update
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBudgetConfiguration'
      responses:
        '204':
          description: Budget configuration updated successfully
          content:
            application/json:
              schema:
                type: boolean
                example: true
        '400':
          description: Bad request, invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Budget configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

    delete:
      tags:
        - Budgets Configurations
      summary: Delete a budget configuration by ID
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the budget configuration to delete
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteBudgetConfigurationBody'
      responses:
        '204':
          description: Budget configuration deleted successfully
        '400':
          description: Bad request, invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Budget configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

components:
  parameters:
    GetBudgetConfigurationsFilters:
      name: filters
      in: query
      required: false
      description: Optional filters for retrieving budget configurations.
      schema:
        type: object
        properties:
          id:
            type: integer
            description: The ID of the budget configuration.
          name:
            type: string
            description: The name of the budget configuration.
          user_id:
            type: string
            format: uuid
            description: The UUID of the user associated with the budget configuration.
          created_at:
            type: string
            format: date
            description: The creation date of the budget configuration in `YYYY-MM-DD` format.
          updated_at:
            type: string
            format: date
            description: The last update date of the budget configuration in `YYYY-MM-DD` format.
          deleted_at:
            type: string
            format: date
            description: The deletion date of the budget configuration in `YYYY-MM-DD` format.
    IDParam:
      name: id
      in: path
      required: true
      description: The ID of the entity to retrieve.
      schema:
        type: integer
  schemas:
    BudgetConfigurationWithBudgets:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'Basic Configuration'
        user_id:
          type: string
          format: uuid
          example: '123e4567-e89b-12d3-a456-426614174000'
        created_at:
          type: string
          format: date
          example: '2024-01-01'
        updated_at:
          type: string
          format: date
          example: '2024-01-02'
        deleted_at:
          type: string
          format: date
          nullable: true
          example: null
        budgets:
          type: array
          items:
            $ref: '#/components/schemas/Budgets'
    Budgets:
      type: object
      properties:
        name:
          type: string
          example: 'Savings'
        percentage:
          type: integer
          example: 30
    BudgetDetails:
      type: object
      properties:
        id:
          type: integer
          format: int32
        user_id:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 30
        percentage:
          type: number
          format: float
        remaining_allocation:
          type: number
          format: float
        budget_configuration_id:
          type: integer
          format: int32
        transfer_to_budget_id:
          type: integer
          format: int32
        monthly_wage_id:
          type: integer
          format: int32
        created_at:
          type: string
          format: date
        updated_at:
          type: string
          format: date
        deleted_at:
          type: string
          format: date
    PostUser:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
        email:
          type: string
        roles:
          type: array
          items:
            type: number
      required:
        - username
        - email
        - roles
    PostBudgetConfiguration:
      type: object
      properties:
        user_id:
          type: string
        budget_configuration_name:
          type: string
        budgets:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              percentage:
                type: integer
                minimum: 1
                maximum: 100
      required:
        - user_id
        - budget_configuration_name
        - budgets
    UpdateBudgetConfiguration:
      type: object
      properties:
        budget_configuration_id:
          type: integer
        user_id:
          type: string
        budget_configuration_name:
          type: string
        budgets:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              percentage:
                type: number
    DeleteBudgetConfigurationBody:
      type: object
      required:
        - user_id
      properties:
        user_id:
          type: string
          description: ID of the user who owns the budget configuration
    ApiError:
      type: object
      properties:
        status:
          type: string
          description: Status of the error response (e.g., "FAIL")
          example: 'FAIL'
        message:
          type: string
          description: Description of the error
          example: 'An unexpected error occurred'
        error_code:
          type: string
          description: Specific error code for the error
          example: 'DatabaseError'