ADHD-Home-Quest/swagger.yml

openapi: 3.0.0
info:
  title: ADHD Home Quest API
  version: 1.0.0
  description: >
    Eine REST-API für die ADHD Home Quest App.
    Diese API bietet Endpunkte für:
    - User-Registrierung und -Login
    - Aufgabenverwaltung (Tasks)
    - Quest-Generierung (Quests)
    - XP & Levelsystem
    - Belohnungen (Rewards) & Achievements
  contact:
    name: ADHD Home Quest Team
    email: adhdhomequest@josunlp.de

servers:
  - url: https://api.adhdhomequest.josunlp.de
    description: Produktions-Server
  - url: https://staging.api.adhdhomequest.josunlp.de
    description: Staging-Server

tags:
  - name: Auth
    description: Endpunkte zur Authentifizierung und User-Verwaltung
  - name: Tasks
    description: Endpunkte zur Aufgabenverwaltung
  - name: Quests
    description: Generierung und Management von Quests
  - name: User
    description: Userbezogene Daten (XP, Level, Achievements)
  - name: Rewards
    description: Rewards und Achievements

paths:
  /auth/register:
    post:
      tags:
        - Auth
      summary: Registriert einen neuen Nutzer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: Nutzer erfolgreich registriert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Ungültige Eingaben

  /auth/login:
    post:
      tags:
        - Auth
      summary: Loggt einen bestehenden Nutzer ein
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Erfolgreich eingeloggt, Access Token wird zurückgegeben
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Ungültige Login-Daten

  /auth/me:
    get:
      tags:
        - Auth
      summary: Liefert Informationen über den eingeloggten Nutzer
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Nutzerinformationen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Nicht autorisiert

  /tasks:
    get:
      tags:
        - Tasks
      summary: Liste alle Tasks des eingeloggten Nutzers auf
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Liste von Tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
    post:
      tags:
        - Tasks
      summary: Erstelle einen neuen Task
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
      responses:
        '201':
          description: Task erstellt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Ungültige Daten

  /tasks/{id}:
    get:
      tags:
        - Tasks
      summary: Hole einen einzelnen Task
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Task gefunden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Task nicht gefunden

    put:
      tags:
        - Tasks
      summary: Aktualisiere einen bestehenden Task
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
      responses:
        '200':
          description: Task aktualisiert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Ungültige Daten
        '404':
          description: Task nicht gefunden

    delete:
      tags:
        - Tasks
      summary: Lösche einen bestehenden Task
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Task gelöscht
        '404':
          description: Task nicht gefunden

  /quests:
    get:
      tags:
        - Quests
      summary: Liste aller aktuell generierten Quests für den Nutzer
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Liste von Quests
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Quest'
    post:
      tags:
        - Quests
      summary: Generiere neue Quests auf Basis der vorhandenen Tasks
      security:
        - BearerAuth: []
      responses:
        '201':
          description: Neue Quests generiert
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Quest'

  /quests/{id}/complete:
    post:
      tags:
        - Quests
      summary: Markiert eine Quest als erledigt und vergibt XP
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Quest erledigt, XP vergeben
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestCompletionResponse'
        '404':
          description: Quest nicht gefunden

  /user/status:
    get:
      tags:
        - User
      summary: Liefert den aktuellen Level, XP und nächste Rewards
      security:
        - BearerAuth: []
      responses:
        '200':
          description: User-Status mit XP, Level und Rewards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStatus'

  /rewards:
    get:
      tags:
        - Rewards
      summary: Liste aller möglichen Rewards / Achievements
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Liste aller Rewards/Achievements
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Reward'

  /rewards/unlocked:
    get:
      tags:
        - Rewards
      summary: Liste der freigeschalteten Rewards für den aktuellen Nutzer
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Liste der freigeschalteten Rewards
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Reward'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    RegisterRequest:
      type: object
      required:
        - name
        - email
        - password
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        password:
          type: string

    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string

    LoginResponse:
      type: object
      properties:
        token:
          type: string
        user:
          $ref: '#/components/schemas/User'

    UserResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'

    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        level:
          type: integer
        xp:
          type: integer

    UserStatus:
      type: object
      properties:
        level:
          type: integer
        xp:
          type: integer
        xp_for_next_level:
          type: integer
        upcoming_rewards:
          type: array
          items:
            $ref: '#/components/schemas/Reward'

    Task:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        description:
          type: string
        category:
          type: string
          enum: [daily, weekend, vacation, work]
        priority:
          type: string
          enum: [low, medium, high]
        due_date:
          type: string
          format: date-time

    CreateTaskRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
        description:
          type: string
        category:
          type: string
          enum: [daily, weekend, vacation, work]
        priority:
          type: string
          enum: [low, medium, high]
        due_date:
          type: string
          format: date-time

    UpdateTaskRequest:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        category:
          type: string
          enum: [daily, weekend, vacation, work]
        priority:
          type: string
          enum: [low, medium, high]
        due_date:
          type: string
          format: date-time

    Quest:
      type: object
      properties:
        id:
          type: integer
        task_id:
          type: integer
        title:
          type: string
        category:
          type: string
        due_date:
          type: string
          format: date-time
        xp_reward:
          type: integer

    QuestCompletionResponse:
      type: object
      properties:
        quest:
          $ref: '#/components/schemas/Quest'
        xp_gained:
          type: integer
        new_level:
          type: integer
        level_up:
          type: boolean

    Reward:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        unlocked_at_level:
          type: integer