openapi: 3.0.3
info:
  title: Family API - Al Rahma Sunday School
  version: 1.0.0
  description: >
    Manage household groupings, students, and guardians that are linked to parents.
    All endpoints expect JWT Bearer authentication.
servers:
  - url: https://your-domain.com/api/v1
security:
  - bearerAuth: []
tags:
  - name: Families
    description: Manage families, students, and guardian relationships

paths:
  /families:
    get:
      tags: [Families]
      summary: List family records
      parameters:
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: per_page
          schema: { type: integer, default: 20 }
      responses:
        "200":
          description: Paginated family list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedFamiliesResponse'

  /families/{id}:
    get:
      tags: [Families]
      summary: Get a specific family
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Family info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponse'
        "404":
          description: Family not found

  /families/student/{id}:
    get:
      tags: [Families]
      summary: Get families that include a specific student
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: One or more families
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedFamiliesResponse'

  /families/{id}/guardians:
    get:
      tags: [Families]
      summary: List guardians linked to a family
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Guardians for the family
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuardiansListResponse'
components:
  schemas:
    Family:
      type: object
      properties:
        id: { type: integer }
        family_name: { type: string, nullable: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        students:
          type: array
          items:
            $ref: '#/components/schemas/StudentSummary'
        guardians:
          type: array
          items:
            $ref: '#/components/schemas/Guardian'

    StudentSummary:
      type: object
      properties:
        id: { type: integer }
        firstname: { type: string }
        lastname: { type: string }
        grade: { type: string, nullable: true }

    Guardian:
      type: object
      properties:
        id: { type: integer }
        family_id: { type: integer }
        firstname: { type: string }
        lastname: { type: string }
        cellphone: { type: string }
        email: { type: string, nullable: true }
        relation: { type: string, nullable: true }

    FamilyResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          $ref: '#/components/schemas/Family'

    PaginatedFamiliesResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Family'
            pagination:
              type: object
              properties:
                current_page: { type: integer }
                per_page: { type: integer }
                total: { type: integer }
                total_pages: { type: integer }

    GuardiansListResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: array
          items:
            $ref: '#/components/schemas/Guardian'