alrahma_sunday_school/public/docs/openapi/supplier_controller.yaml

openapi: 3.0.3
info:
  title: Supplier API - Al Rahma Sunday School
  version: 1.0.0
  description: >
    Endpoints for managing vendor and supplier records used by the school.
servers:
  - url: https://your-domain.com/api/v1
security:
  - bearerAuth: []
tags:
  - name: Suppliers
    description: CRUD for supplier data

paths:
  /suppliers:
    get:
      tags: [Suppliers]
      summary: List suppliers
      parameters:
        - in: query
          name: q
          schema: { type: string }
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: per_page
          schema: { type: integer, default: 20 }
      responses:
        "200":
          description: Suppliers paginated list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSuppliersResponse'
    post:
      tags: [Suppliers]
      summary: Create a supplier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierRequest'
      responses:
        "201":
          description: Supplier created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplierResponse'

  /suppliers/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: integer }
    get:
      tags: [Suppliers]
      summary: Get supplier details
      responses:
        "200":
          description: Supplier data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplierResponse'
        "404":
          description: Not found
    put:
      tags: [Suppliers]
      summary: Update supplier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierRequest'
      responses:
        "200":
          description: Supplier updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplierResponse'
    delete:
      tags: [Suppliers]
      summary: Delete supplier
      responses:
        "200":
          description: Supplier deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccess'

components:
  schemas:
    Supplier:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        email: { type: string, nullable: true }
        phone: { type: string, nullable: true }
        address: { type: string, nullable: true }
        notes: { type: string, nullable: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    SupplierRequest:
      type: object
      required: [name]
      properties:
        name: { type: string }
        email: { type: string, nullable: true }
        phone: { type: string, nullable: true }
        address: { type: string, nullable: true }
        notes: { type: string, nullable: true }

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

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

    BasicSuccess:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data: {}