openapi: 3.0.3
info:
  title: Authentication API
  version: 1.0.0
servers:
  - url: https://your-domain.com/api/v1
    description: Production
  - url: http://localhost:8080/api/v1
    description: Local
tags:
  - name: Authentication
paths:
  /login:
    post:
      tags: [Authentication]
      summary: Obtain a JWT token for a user
      description: Authenticate with valid credentials to receive a JWT token and user summary.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                  example: admin@example.com
                password:
                  type: string
                  minLength: 8
                  example: 12345678
      responses:
        "200":
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginSuccess'
        "400":
          description: Missing email or password
        "401":
          description: Invalid credentials
        "403":
          description: Account suspended
        "429":
          description: Too many attempts from this IP address
      security: []
  /register:
    post:
      tags: [Authentication]
      summary: Create a new user account (parent registration)
      description: Open registration endpoint that creates a parent account and returns the created profile.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        "201":
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterSuccess'
        "400":
          description: Invalid request data
        "422":
          description: Validation failure (e.g., email already registered)
        "500":
          description: Server error while creating user
      security: []
components:
  schemas:
    LoginSuccess:
      type: object
      properties:
        status:
          type: boolean
          example: true
        token:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        user:
          type: object
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: Admin User
        roles:
          type: object
          additionalProperties:
            type: boolean
          example:
            admin: true
    RegisterRequest:
      type: object
      required: [firstname, lastname, email, password, captcha_answer]
      properties:
        firstname:
          type: string
          example: Jane
        lastname:
          type: string
          example: Doe
        email:
          type: string
          format: email
          example: parent@example.com
        password:
          type: string
          minLength: 8
          example: StrongPass123
        phone:
          type: string
          nullable: true
          example: "+1-410-555-1234"
        captcha_answer:
          type: string
          example: "5"
    RegisterSuccess:
      type: object
      properties:
        status:
          type: boolean
          example: true
        message:
          type: string
          example: Registration successful. Please verify your email.
        data:
          type: object
          properties:
            user:
              type: object
              properties:
                id: { type: integer, example: 101 }
                firstname: { type: string, example: "Jane" }
                lastname: { type: string, example: "Doe" }
                email: { type: string, format: email, example: "parent@example.com" }
                school_id: { type: string, example: "SCH-0001" }