openapi: 3.1.0
info:
  title: Mployr API - Complete Documentation
  description: Complete API documentation for the Mployr HR/Payroll application covering all endpoints and functionality
  version: 1.0.0
  contact:
    name: Mployr Support
    email: support@mployr.com
    url: https://mployr.com/support
  license:
    name: Proprietary
    url: https://mployr.com/terms

servers:
  - url: https://api.mployr.com/v1
    description: Production server
  - url: https://dev.mployr.com/v1
    description: Development server
  - url: http://localhost/api
    description: Local development server

tags:
  - name: Authentication
    description: User authentication and authorization endpoints
  - name: People Management
    description: Employee and people data management
  - name: Addresses
    description: Address management and operations
  - name: Emails
    description: Email management and operations
  - name: Phones
    description: Phone number management and operations
  - name: Organisations
    description: Organization and company management
  - name: Awards
    description: Awards and agreements management
  - name: Document Templates
    description: Document templates, placeholders, and document records management
  - name: Admin
    description: Administrative operations and management

# components
components:
  # ---- AGGREGATED SCHEMAS (from schemas/*.yaml) ----
  schemas:
    # from schemas/common.yaml
    # Common response schemas
    UnauthorizedResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Unauthorized"
        error:
          type: string
          example: "Authentication required"
    
    ForbiddenResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Forbidden"
        error:
          type: string
          example: "Insufficient permissions"
    
    NotFoundResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Not found"
        error:
          type: string
          example: "Resource not found"
    
    ValidationErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Validation failed"
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            email:
              - "The email field is required."
            password:
              - "The password must be at least 8 characters."
    
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 15
        total:
          type: integer
          example: 100
        last_page:
          type: integer
          example: 7
        from:
          type: integer
          example: 1
        to:
          type: integer
          example: 15
    
    # Base entity properties
    BaseEntity:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier
          example: 1
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
          example: "2024-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: "2024-01-01T00:00:00Z"
    # from schemas/requests.yaml
    # Request schemas for API endpoints based on actual database structure
    
    # Person/Name request schemas
    PersonRequest:
      type: object
      required:
        - status
        - business_id
      properties:
        first_name:
          type: string
          nullable: true
          description: First name
          example: "John"
        last_name:
          type: string
          nullable: true
          description: Last name
          example: "Doe"
        email:
          type: string
          format: email
          nullable: true
          description: Email address
          example: "john@example.com"
        phone:
          type: string
          nullable: true
          description: Phone number
          example: "+61412345678"
        date_of_birth:
          type: string
          format: date
          nullable: true
          description: Date of birth
          example: "1990-01-01"
        employee_id:
          type: string
          nullable: true
          description: Employee ID
          example: "EMP001"
        external_id:
          type: string
          nullable: true
          description: External ID
          example: "EXT123"
        position:
          type: string
          nullable: true
          description: Job position
          example: "Software Engineer"
        status:
          type: string
          enum: [active, inactive, terminated]
          description: Person status
          example: "active"
        business_id:
          type: integer
          description: Associated business ID (required)
          example: 1
        user_id:
          type: integer
          nullable: true
          description: Associated user ID
          example: 1
    
    PersonProfileRequest:
      type: object
      properties:
        first_name:
          type: string
          description: First name
          example: "John"
        middle_name:
          type: string
          description: Middle name
          example: "Michael"
        last_name:
          type: string
          description: Last name
          example: "Doe"
        legal_name:
          type: string
          description: Legal name
          example: "John Michael Doe"
        preferred_first_name:
          type: string
          description: Preferred first name
          example: "Johnny"
        preferred_last_name:
          type: string
          description: Preferred last name
          example: "Smith"
        preferred_name:
          type: string
          description: Preferred full name
          example: "Johnny Smith"
        display_name:
          type: string
          description: Display name
          example: "Johnny Smith"
        active:
          type: boolean
          description: Whether the name record is active
          example: true
        start_date:
          type: string
          format: date
          description: Start date for the name
          example: "2024-01-01"
        end_date:
          type: string
          format: date
          nullable: true
          description: End date for the name
          example: "2025-12-31"
    
    EmergencyContactRequest:
      type: object
      required:
        - name
        - relationship
        - phone
      properties:
        name:
          type: string
          description: Contact name
          example: "Jane Doe"
        relationship:
          type: string
          description: Relationship to person
          example: "Spouse"
        phone:
          type: string
          description: Phone number
          example: "+61412345678"
        email:
          type: string
          format: email
          nullable: true
          description: Email address
          example: "jane@example.com"
        address:
          type: string
          nullable: true
          description: Address
          example: "123 Main St, Sydney NSW 2000"
    
    BankAccountRequest:
      type: object
      required:
        - account_name
        - bsb
        - account_number
      properties:
        account_name:
          type: string
          description: Account holder name
          example: "John Doe"
        bsb:
          type: string
          description: BSB number
          example: "123-456"
        account_number:
          type: string
          description: Account number
          example: "12345678"
        account_type:
          type: string
          enum: [savings, checking]
          default: "savings"
          description: Account type
          example: "savings"
        percentage:
          type: number
          minimum: 0
          maximum: 100
          nullable: true
          description: Percentage for split payments
          example: 100
    
    SuperFundRequest:
      type: object
      required:
        - fund_name
        - member_number
      properties:
        fund_name:
          type: string
          description: Superannuation fund name
          example: "AustralianSuper"
        member_number:
          type: string
          description: Member number
          example: "123456789"
        usi:
          type: string
          nullable: true
          description: Unique Superannuation Identifier
          example: "12345678901"
        percentage:
          type: number
          minimum: 0
          maximum: 100
          nullable: true
          description: Percentage contribution
          example: 9.5
    
    # Address request schemas
    AddressRequest:
      type: object
      required:
        - line_1
        - city
        - regions_id
        - countries_id
        - postal_code
      properties:
        active:
          type: boolean
          default: true
          description: Whether the address is active
          example: true
        line_1:
          type: string
          description: Primary address line
          example: "123 Main Street"
        line_2:
          type: string
          description: Secondary address line
          example: "Unit 4"
        city:
          type: string
          description: City
          example: "Sydney"
        regions_id:
          type: integer
          description: Region ID (state/territory)
          example: 1
        countries_id:
          type: integer
          description: Country ID
          example: 1
        postal_code:
          type: string
          description: Postal code
          example: "2000"
        formatted:
          type: string
          description: Formatted address
          example: "123 Main Street, Unit 4, Sydney NSW 2000, Australia"
    
    # Email request schemas
    EmailRequest:
      type: object
      required:
        - value
      properties:
        value:
          type: string
          format: email
          description: Email address
          example: "john@example.com"
        display:
          type: string
          nullable: true
          description: Display name for the email
          example: "Work Email"
        validated_at:
          type: string
          format: date-time
          nullable: true
          description: Email validation timestamp
          example: "2024-01-01T00:00:00Z"
    
    # Phone request schemas
    PhoneRequest:
      type: object
      required:
        - value
        - countries_id
      properties:
        active:
          type: boolean
          default: true
          description: Whether the phone is active
          example: true
        value:
          type: string
          description: Phone number
          example: "+61412345678"
        countries_id:
          type: integer
          description: Country ID
          example: 1
    
    # Organisation request schemas
    OrganisationRequest:
      type: object
      required:
        - name
      properties:
        active:
          type: boolean
          default: true
          description: Whether the organisation is active
          example: true
        name:
          type: string
          description: Organisation name
          example: "Mployr Pty Ltd"
    
    # Organisation Entity request schemas
    OrganisationEntityRequest:
      type: object
      required:
        - legal_name
        - tax_identifier
      properties:
        active:
          type: boolean
          default: true
          description: Whether the organisation entity is active
          example: true
        legal_name:
          type: string
          description: Legal name
          example: "Mployr Pty Ltd"
        trading_name:
          type: string
          nullable: true
          description: Trading name
          example: "Mployr"
        organisation_identifirer:
          type: string
          nullable: true
          description: Organisation identifier
          example: "12345678901"
        tax_identifier:
          type: string
          description: Tax identifier (ABN)
          example: "12345678901"
    
    # Award request schemas
    AwardRequest:
      type: object
      required:
        - code
        - name
      properties:
        code:
          type: string
          maxLength: 8
          description: Award code
          example: "MA000004"
        name:
          type: string
          description: Award name
          example: "General Retail Industry Award [MA000004]"
    
    # Award Management request schemas
    AwardManagementRequest:
      type: object
      required:
        - code
        - name
      properties:
        code:
          type: string
          maxLength: 255
          description: Award management code (must be unique)
          example: "MA000004-2024"
        name:
          type: string
          maxLength: 255
          description: Award management name
          example: "General Retail Industry Award 2024"
    
    # Award Configuration request schemas
    AwardConfigurationRequest:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          maxLength: 255
          description: Configuration key
          example: "minimum_wage"
        value:
          type: string
          maxLength: 255
          description: Configuration value
          example: "25.50"
    
    # Email Management request schemas
    EmailManagementRequest:
      type: object
      required:
        - code
        - name
      properties:
        code:
          type: string
          maxLength: 255
          description: Email management code (must be unique)
          example: "welcome-email"
        name:
          type: string
          maxLength: 255
          description: Email management name
          example: "Welcome Email Template"
    
    # User request schemas
    UserRequest:
      type: object
      required:
        - email
        - password
      properties:
        first_name:
          type: string
          nullable: true
          description: First name
          example: "John"
        last_name:
          type: string
          nullable: true
          description: Last name
          example: "Doe"
        email:
          type: string
          format: email
          description: Email address
          example: "john@example.com"
        password:
          type: string
          minLength: 8
          description: Password
          example: "password123"
        password_confirmation:
          type: string
          description: Password confirmation
          example: "password123"
        role:
          type: string
          enum: [Admin, Employee, Business_Admin, admin, employee, business_admin]
          description: User role (accepts both capitalized and lowercase formats)
          example: "Admin"
        business_id:
          type: integer
          nullable: true
          description: Associated business ID
          example: 1
    
    # Business request schemas
    BusinessRequest:
      type: object
      properties:
        name:
          type: string
          description: Business name (legal name)
          example: "Acme Corporation Pty Ltd"
        contact_email:
          type: string
          format: email
          description: Primary contact email address
          example: "contact@acme.com"
        phone:
          type: string
          description: Primary phone number
          example: "+61412345678"
        address:
          type: object
          description: Business address
          properties:
            line_1:
              type: string
              description: Primary address line
              example: "123 Business Street"
            line_2:
              type: string
              nullable: true
              description: Secondary address line
              example: "Suite 100"
            city:
              type: string
              description: City
              example: "Sydney"
            regions_id:
              type: integer
              description: Region ID (state/territory)
              example: 1
            countries_id:
              type: integer
              description: Country ID
              example: 1
            postal_code:
              type: string
              description: Postal code
              example: "2000"
        note:
          type: string
          nullable: true
          description: Additional notes about the business
          example: "Established in 2020"
    
    # Name request schemas
    NameRequest:
      type: object
      required:
        - first_name
        - last_name
      properties:
        first_name:
          type: string
          description: First name
          example: "John"
        middle_name:
          type: string
          nullable: true
          description: Middle name
          example: "Michael"
        last_name:
          type: string
          description: Last name
          example: "Doe"
        legal_name:
          type: string
          description: Legal name (full name)
          example: "John Michael Doe"
        active:
          type: boolean
          default: true
          description: Whether the name record is active
          example: true
    
    # Document request schemas
    DocumentRequest:
      type: object
      required:
        - title
        - content
      properties:
        title:
          type: string
          maxLength: 255
          description: Document template title
          example: "Employment Contract Template"
        content:
          type: string
          description: Document content (HTML supported, placeholders in format {{Model.field}})
          example: "<p>Contract between {{Organization.name}} and {{People.first_name}} {{People.last_name}}...</p>"
        status:
          type: string
          enum: [draft, published]
          default: draft
          description: Document status
          example: "draft"
    
    DocumentRecordRequest:
      type: object
      required:
        - record_data
      properties:
        document_id:
          type: integer
          description: Document template ID (required for POST)
          example: 1
        person_id:
          type: integer
          nullable: true
          description: ID of the person selected when creating this document record
          example: 5
        record_data:
          type: object
          description: |
            Key-value pairs where keys are placeholder keys and values are the actual data. 
            Frontend is responsible for populating all required placeholders. 
    
            **Data Sources:**
            - Person data: Fetch via `GET /api/people/{people}` when selecting a person
            - Business data: Should already be loaded (same business as the authenticated user)
    
            **Mapping Example:**
            - From person response: `first_name` → `People.first_name`
            - From person response: `last_name` → `People.last_name`
            - From person response: `email` → `People.email`
            - From business data: `name` → `Business.name` or `Organization.name`
            - From business data: `contact_email` → `Business.email` or `Organization.email`
    
            All placeholders found in the template must be provided in `record_data`.
          additionalProperties: true
          example:
            People.first_name: "John"
            People.last_name: "Doe"
            People.email: "john.doe@example.com"
            Business.name: "Acme Corp"
            Organization.name: "Acme Corp"
            Business.email: "contact@acmecorp.com"
    # from schemas/responses.yaml
    # Response schemas for API endpoints based on actual database structure
    
    # Person/Name response schemas
    Person:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            active:
              type: boolean
              description: Whether the name record is active
              example: true
            first_name:
              type: string
              description: First name
              example: "John"
            middle_name:
              type: string
              description: Middle name
              example: "Michael"
            last_name:
              type: string
              description: Last name
              example: "Doe"
            legal_name:
              type: string
              description: Legal name
              example: "John Michael Doe"
            full_name:
              type: string
              description: Full name
              example: "John Michael Doe"
            email:
              type: string
              format: email
              nullable: true
              description: Active email address (from activeEmail relationship)
              example: "john@example.com"
            phone:
              type: string
              nullable: true
              description: Active phone number (from activePhone relationship)
              example: "+61412345678"
            date_of_birth:
              type: string
              format: date
              nullable: true
              description: Date of birth
              example: "1990-01-01"
            employee_id:
              type: string
              nullable: true
              description: Employee ID
              example: "EMP001"
            external_id:
              type: string
              nullable: true
              description: External ID
              example: "EXT123"
            position:
              type: string
              nullable: true
              description: Job position
              example: "Software Engineer"
            status:
              type: string
              enum: [active, inactive, terminated]
              nullable: true
              description: Person status
              example: "active"
            business_id:
              type: integer
              description: Associated business ID (required)
              example: 1
            user_id:
              type: integer
              nullable: true
              description: Associated user ID
              example: 1
            addresses:
              type: array
              items:
                $ref: "#/components/schemas/Address"
            emails:
              type: array
              items:
                $ref: "#/components/schemas/Email"
            phones:
              type: array
              items:
                $ref: "#/components/schemas/Phone"
    
    PersonProfile:
      allOf:
        - $ref: "#/components/schemas/Person"
        - type: object
          properties:
            preferred_first_name:
              type: string
              nullable: true
              description: Preferred first name
              example: "Johnny"
            preferred_last_name:
              type: string
              nullable: true
              description: Preferred last name
              example: "Smith"
            preferred_name:
              type: string
              nullable: true
              description: Preferred full name
              example: "Johnny Smith"
            display_name:
              type: string
              nullable: true
              description: Display name
              example: "Johnny Smith"
            start_date:
              type: string
              format: date
              description: Start date for the name
              example: "2024-01-01"
            end_date:
              type: string
              format: date
              nullable: true
              description: End date for the name
              example: "2025-12-31"
            emergency_contacts:
              type: array
              items:
                $ref: "#/components/schemas/EmergencyContact"
            bank_accounts:
              type: array
              items:
                $ref: "#/components/schemas/BankAccount"
            super_funds:
              type: array
              items:
                $ref: "#/components/schemas/SuperFund"
    
    EmergencyContact:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            name:
              type: string
              description: Contact name
              example: "Jane Doe"
            relationship:
              type: string
              description: Relationship to person
              example: "Spouse"
            phone:
              type: string
              description: Phone number
              example: "+61412345678"
            email:
              type: string
              format: email
              nullable: true
              description: Email address
              example: "jane@example.com"
            address:
              type: string
              nullable: true
              description: Address
              example: "123 Main St, Sydney NSW 2000"
    
    BankAccount:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            account_name:
              type: string
              description: Account holder name
              example: "John Doe"
            bsb:
              type: string
              description: BSB number
              example: "123-456"
            account_number:
              type: string
              description: Account number (masked)
              example: "****5678"
            account_type:
              type: string
              enum: [savings, checking]
              description: Account type
              example: "savings"
            percentage:
              type: number
              minimum: 0
              maximum: 100
              nullable: true
              description: Percentage for split payments
              example: 100
    
    SuperFund:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            fund_name:
              type: string
              description: Superannuation fund name
              example: "AustralianSuper"
            member_number:
              type: string
              description: Member number (masked)
              example: "****6789"
            usi:
              type: string
              nullable: true
              description: Unique Superannuation Identifier
              example: "12345678901"
            percentage:
              type: number
              minimum: 0
              maximum: 100
              nullable: true
              description: Percentage contribution
              example: 9.5
    
    # Address response schemas
    Address:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            active:
              type: boolean
              description: Whether the address is active
              example: true
            line_1:
              type: string
              description: Primary address line
              example: "123 Main Street"
            line_2:
              type: string
              description: Secondary address line
              example: "Unit 4"
            city:
              type: string
              description: City
              example: "Sydney"
            regions_id:
              type: integer
              description: Region ID (state/territory)
              example: 1
            countries_id:
              type: integer
              description: Country ID
              example: 1
            postal_code:
              type: string
              description: Postal code
              example: "2000"
            formatted:
              type: string
              description: Formatted address
              example: "123 Main Street, Unit 4, Sydney NSW 2000, Australia"
            region:
              $ref: "#/components/schemas/Region"
            country:
              $ref: "#/components/schemas/Country"
    
    # Email response schemas
    Email:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            value:
              type: string
              format: email
              description: Email address
              example: "john@example.com"
            display:
              type: string
              nullable: true
              description: Display name for the email
              example: "Work Email"
            validated_at:
              type: string
              format: date-time
              nullable: true
              description: Email validation timestamp
              example: "2024-01-01T00:00:00Z"
    
    # Phone response schemas
    Phone:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            active:
              type: boolean
              description: Whether the phone is active
              example: true
            value:
              type: string
              description: Phone number
              example: "+61412345678"
            countries_id:
              type: integer
              description: Country ID
              example: 1
            country:
              $ref: "#/components/schemas/Country"
    
    # Organisation response schemas
    Organisation:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            active:
              type: boolean
              description: Whether the organisation is active
              example: true
            name:
              type: string
              description: Organisation name
              example: "Mployr Pty Ltd"
    
    # Organisation Entity response schemas
    OrganisationEntity:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            active:
              type: boolean
              description: Whether the organisation entity is active
              example: true
            legal_name:
              type: string
              description: Legal name
              example: "Mployr Pty Ltd"
            trading_name:
              type: string
              nullable: true
              description: Trading name
              example: "Mployr"
            organisation_identifirer:
              type: string
              nullable: true
              description: Organisation identifier
              example: "12345678901"
            tax_identifier:
              type: string
              description: Tax identifier (ABN)
              example: "12345678901"
    
    # Award response schemas
    Award:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            code:
              type: string
              description: Award code
              example: "MA000004"
            name:
              type: string
              description: Award name
              example: "General Retail Industry Award [MA000004]"
    
    # Award Management response schemas
    AwardManagement:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            code:
              type: string
              description: Award management code
              example: "MA000004-2024"
            name:
              type: string
              description: Award management name
              example: "General Retail Industry Award 2024"
            deleted_at:
              type: string
              format: date-time
              nullable: true
              description: Soft delete timestamp
              example: null
    
    # Award Configuration response schemas
    AwardConfiguration:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            award_management_id:
              type: integer
              description: Associated award management ID
              example: 1
            key:
              type: string
              description: Configuration key
              example: "minimum_wage"
            value:
              type: string
              description: Configuration value
              example: "25.50"
    
    # Email Management response schemas
    EmailManagement:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            code:
              type: string
              description: Email management code
              example: "welcome-email"
            name:
              type: string
              description: Email management name
              example: "Welcome Email Template"
            deleted_at:
              type: string
              format: date-time
              nullable: true
              description: Soft delete timestamp
              example: null
    
    # User response schemas
    User:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            name:
              type: string
              description: Full name
              example: "John Doe"
            email:
              type: string
              format: email
              description: Email address
              example: "john@example.com"
            email_verified_at:
              type: string
              format: date-time
              nullable: true
              description: Email verification timestamp
              example: "2024-01-01T00:00:00Z"
            role:
              type: string
              nullable: true
              enum: [Admin, Employee, Business_Admin]
              description: User role (capitalized format)
              example: "Admin"
            business_id:
              type: integer
              nullable: true
              description: Associated business ID
              example: 1
            first_name:
              type: string
              nullable: true
              description: First name
              example: "John"
            last_name:
              type: string
              nullable: true
              description: Last name
              example: "Doe"
    
    UserProfile:
      allOf:
        - $ref: "#/components/schemas/User"
        - type: object
          properties:
            profile_photo_url:
              type: string
              nullable: true
              description: Profile photo URL
              example: "https://example.com/photos/profile.jpg"
            preferences:
              type: object
              description: User preferences
              additionalProperties: true
    
    # Region response schemas
    Region:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            active:
              type: boolean
              description: Whether the region is active
              example: true
            name:
              type: string
              description: Region name
              example: "New South Wales"
            code:
              type: string
              description: Region code
              example: "NSW"
    
    # Country response schemas
    Country:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            active:
              type: boolean
              description: Whether the country is active
              example: true
            name:
              type: string
              description: Country name
              example: "Australia"
            code:
              type: string
              description: Country code
              example: "AU"
            display_name:
              type: string
              description: Display name
              example: "Australia"
    
    # Business response schemas
    Business:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            name:
              type: string
              nullable: true
              description: Current business name (from active name record)
              example: "Acme Corporation Pty Ltd"
            contact_email:
              type: string
              nullable: true
              description: Current primary contact email (from active email record)
              example: "contact@acme.com"
            phone:
              type: string
              nullable: true
              description: Current primary phone number (from active phone record)
              example: "+61412345678"
            branding:
              type: string
              nullable: true
              description: Business branding information
              example: null
            users:
              type: array
              description: Users associated with this business
              items:
                $ref: "#/components/schemas/User"
            people:
              type: array
              description: People associated with this business
              items:
                $ref: "#/components/schemas/Person"
    
    # Name response schemas
    Name:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            first_name:
              type: string
              nullable: true
              description: First name
              example: "John"
            middle_name:
              type: string
              nullable: true
              description: Middle name
              example: "Michael"
            last_name:
              type: string
              nullable: true
              description: Last name
              example: "Doe"
            legal_name:
              type: string
              nullable: true
              description: Legal name (full name)
              example: "John Michael Doe"
            active:
              type: boolean
              description: Whether the name record is active
              example: true
    
    # Document response schemas
    Document:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            title:
              type: string
              description: Document template title
              example: "Employment Contract Template"
            content:
              type: string
              description: Document template content with placeholders
              example: "<p>This is an employment contract for {{People.first_name}} {{People.last_name}}.</p>"
            status:
              type: string
              enum: [draft, published]
              description: Document template status
              example: "draft"
    
    DocumentRecord:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - type: object
          properties:
            document_id:
              type: integer
              description: Associated document template ID (points to the specific template version used when this record was created)
              example: 1
            person_id:
              type: integer
              nullable: true
              description: ID of the person selected when creating this document record
              example: 5
            record_data:
              type: object
              description: Key-value pairs with placeholder data
              additionalProperties: true
              example:
                People.first_name: "John"
                People.last_name: "Doe"
                Organization.name: "Acme Corp"
            version_number:
              type: integer
              description: Version number of this document record (SCD Type 2)
              example: 1
            template_version_number:
              type: integer
              description: Version number of the template used when this record was created
              example: 2
            effective_start_date:
              type: string
              format: date-time
              description: When this version became effective
              example: "2024-01-20T10:00:00Z"
            effective_end_date:
              type: string
              format: date-time
              nullable: true
              description: When this version ended (null if current)
              example: null
            is_current:
              type: boolean
              description: Whether this is the current version
              example: true
            is_finalized:
              type: boolean
              description: Whether this record is finalized and cannot be edited
              example: false
            created_by:
              type: integer
              description: User ID who created this record
              example: 5
    
    # Placeholder response schemas
    Placeholder:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the placeholder
          example: 1
        key:
          type: string
          description: Placeholder key in format "Model.field" (e.g., "People.first_name")
          example: "People.first_name"
        label:
          type: string
          description: Human-readable label for the placeholder
          example: "People First Name"
        source_table:
          type: string
          description: Source table/model name
          example: "People"
        source_column:
          type: string
          description: Source column/field name
          example: "first_name"
        data_type:
          type: string
          nullable: true
          description: Data type of the field (e.g., "string", "integer", "date")
          example: "string"
        description:
          type: string
          nullable: true
          description: Description of what this placeholder represents
          example: "First name from People"
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from login endpoint. Include the token in the Authorization header as 'Bearer {token}'

# security (applies to all endpoints unless overridden)
security:
  - BearerAuth: []

# ---- AGGREGATED PATHS (from *.yaml) ----
paths:
  # from addresses.yaml
    /addresses:
      get:
        tags:
          - Addresses
        summary: List addresses
        description: Get paginated list of addresses
        operationId: listAddresses
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
            description: Items per page
          - in: query
            name: search
            schema:
              type: string
            description: Search by address details
          - in: query
            name: type
            schema:
              type: string
              enum: [home, work, postal, other]
            description: Filter by address type
        responses:
          "200":
            description: List of addresses
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        items:
                          type: array
                          items:
                            $ref: "#/components/schemas/Address"
                        pagination:
                          $ref: "#/components/schemas/Pagination"
  
      post:
        tags:
          - Addresses
        summary: Create address
        description: Create a new address record
        operationId: createAddress
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressRequest"
        responses:
          "201":
            description: Address created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Address"
  
    /addresses/{address}:
      get:
        tags:
          - Addresses
        summary: Get address details
        description: Get detailed information about a specific address
        operationId: getAddress
        security:
          - BearerAuth: []
        parameters:
          - name: address
            in: path
            required: true
            schema:
              type: integer
            description: Address ID
        responses:
          "200":
            description: Address details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Address"
  
      put:
        tags:
          - Addresses
        summary: Update address
        description: Update address information
        operationId: updateAddress
        security:
          - BearerAuth: []
        parameters:
          - name: address
            in: path
            required: true
            schema:
              type: integer
            description: Address ID
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressRequest"
        responses:
          "200":
            description: Address updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Address"
  
      delete:
        tags:
          - Addresses
        summary: Delete address
        description: Delete an address record
        operationId: deleteAddress
        security:
          - BearerAuth: []
        parameters:
          - name: address
            in: path
            required: true
            schema:
              type: integer
            description: Address ID
        responses:
          "200":
            description: Address deleted successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: "Address deleted successfully"
  # from auth.yaml
    /login:
      post:
        tags:
          - Authentication
        summary: User login
        description: Authenticate user and return access token
        operationId: login
        security: [] # No auth required for login
        requestBody:
          required: true
          content:
            application/json:
              schema:
                type: object
                required:
                  - email
                  - password
                properties:
                  email:
                    type: string
                    format: email
                    description: User email address
                    example: "user@example.com"
                  password:
                    type: string
                    description: User password
                    example: "password123"
        responses:
          "200":
            description: Login successful
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        user:
                          $ref: "#/components/schemas/User"
                        token:
                          type: string
                          description: JWT access token
                          example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
          "401":
            description: Invalid credentials
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/UnauthorizedResponse"
          "422":
            description: Validation error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/ValidationErrorResponse"
  
    /register:
      post:
        tags:
          - Authentication
        summary: User registration
        description: Register a new user account
        operationId: register
        security: [] # No auth required for registration
        requestBody:
          required: true
          content:
            application/json:
              schema:
                type: object
                required:
                  - name
                  - email
                  - password
                  - password_confirmation
                properties:
                  name:
                    type: string
                    description: Full name
                    example: "John Doe"
                  email:
                    type: string
                    format: email
                    description: Email address
                    example: "john@example.com"
                  password:
                    type: string
                    minLength: 8
                    description: Password
                    example: "password123"
                  password_confirmation:
                    type: string
                    description: Password confirmation
                    example: "password123"
        responses:
          "201":
            description: Registration successful
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        user:
                          $ref: "#/components/schemas/User"
                        token:
                          type: string
                          description: JWT access token
                          example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
          "422":
            description: Validation error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/ValidationErrorResponse"
  
    /logout:
      post:
        tags:
          - Authentication
        summary: User logout
        description: Logout user and invalidate token
        operationId: logout
        security:
          - BearerAuth: []
        responses:
          "200":
            description: Logout successful
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: "Successfully logged out"
          "401":
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/UnauthorizedResponse"
  
    /user:
      get:
        tags:
          - Authentication
        summary: Get current user
        description: Get authenticated user information
        operationId: getCurrentUser
        security:
          - BearerAuth: []
        responses:
          "200":
            description: User information
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/User"
          "401":
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/UnauthorizedResponse"
  
    /user/profile:
      get:
        tags:
          - Authentication
        summary: Get user profile
        description: Get detailed profile information for authenticated user
        operationId: getUserProfile
        security:
          - BearerAuth: []
        responses:
          "200":
            description: User profile
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/UserProfile"
          "401":
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/UnauthorizedResponse"
  # from award-configurations.yaml
    /award-managements/{award_management}/configurations:
      get:
        tags:
          - Award Configurations
        summary: List configurations for an award management
        operationId: listAwardConfigurations
        security:
          - BearerAuth: []
        parameters:
          - name: award_management
            in: path
            required: true
            schema:
              type: integer
          - in: query
            name: page
            schema:
              type: integer
          - in: query
            name: per_page
            schema:
              type: integer
        responses:
          "200":
            description: List of configurations
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        items:
                          type: array
                          items:
                            $ref: "#/components/schemas/AwardConfiguration"
                        pagination:
                          $ref: "#/components/schemas/Pagination"
  
      post:
        tags:
          - Award Configurations
        summary: Create configuration for an award management
        operationId: createAwardConfiguration
        security:
          - BearerAuth: []
        parameters:
          - name: award_management
            in: path
            required: true
            schema:
              type: integer
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AwardConfigurationRequest"
        responses:
          "201":
            description: Configuration created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/AwardConfiguration"
  
    /award-managements/{award_management}/configurations/{configuration}:
      get:
        tags:
          - Award Configurations
        summary: Get configuration details
        operationId: getAwardConfiguration
        security:
          - BearerAuth: []
        parameters:
          - name: award_management
            in: path
            required: true
            schema:
              type: integer
          - name: configuration
            in: path
            required: true
            schema:
              type: integer
        responses:
          "200":
            description: Configuration details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/AwardConfiguration"
  
      put:
        tags:
          - Award Configurations
        summary: Update configuration
        operationId: updateAwardConfiguration
        security:
          - BearerAuth: []
        parameters:
          - name: award_management
            in: path
            required: true
            schema:
              type: integer
          - name: configuration
            in: path
            required: true
            schema:
              type: integer
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AwardConfigurationRequest"
        responses:
          "200":
            description: Configuration updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/AwardConfiguration"
  
      delete:
        tags:
          - Award Configurations
        summary: Delete configuration
        operationId: deleteAwardConfiguration
        security:
          - BearerAuth: []
        parameters:
          - name: award_management
            in: path
            required: true
            schema:
              type: integer
          - name: configuration
            in: path
            required: true
            schema:
              type: integer
        responses:
          "200":
            description: Configuration deleted successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: "Award configuration deleted successfully"
  # from award-management.yaml
    /award-managements:
      get:
        tags:
          - Award Management
        summary: List award managements
        description: Get paginated list of award managements
        operationId: listAwardManagements
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
            description: Items per page
        responses:
          "200":
            description: List of award managements
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        items:
                          type: array
                          items:
                            $ref: "#/components/schemas/AwardManagement"
                        pagination:
                          $ref: "#/components/schemas/Pagination"
  
      post:
        tags:
          - Award Management
        summary: Create award management
        description: Create a new award management
        operationId: createAwardManagement
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AwardManagementRequest"
        responses:
          "201":
            description: Award management created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/AwardManagement"
  
    /award-managements/{award_management}:
      get:
        tags:
          - Award Management
        summary: Get award management details
        operationId: getAwardManagement
        security:
          - BearerAuth: []
        parameters:
          - name: award_management
            in: path
            required: true
            schema:
              type: integer
        responses:
          "200":
            description: Award management details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/AwardManagement"
  
      put:
        tags:
          - Award Management
        summary: Update award management
        operationId: updateAwardManagement
        security:
          - BearerAuth: []
        parameters:
          - name: award_management
            in: path
            required: true
            schema:
              type: integer
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AwardManagementRequest"
        responses:
          "200":
            description: Award management updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/AwardManagement"
  
      delete:
        tags:
          - Award Management
        summary: Delete award management
        operationId: deleteAwardManagement
        security:
          - BearerAuth: []
        parameters:
          - name: award_management
            in: path
            required: true
            schema:
              type: integer
        responses:
          "200":
            description: Award management deleted successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: "Award management deleted successfully"
  # from awards.yaml
    /awards:
      get:
        tags:
          - Awards
        summary: List awards
        description: Get paginated list of awards and agreements
        operationId: listAwards
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
            description: Items per page
          - in: query
            name: search
            schema:
              type: string
            description: Search by award name
          - in: query
            name: status
            schema:
              type: string
              enum: [active, inactive, expired]
            description: Filter by award status
        responses:
          "200":
            description: List of awards
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        items:
                          type: array
                          items:
                            $ref: "#/components/schemas/Award"
                        pagination:
                          $ref: "#/components/schemas/Pagination"
  
      post:
        tags:
          - Awards
        summary: Create award
        description: Create a new award or agreement record
        operationId: createAward
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AwardRequest"
        responses:
          "201":
            description: Award created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Award"
  
    /awards/{award}:
      get:
        tags:
          - Awards
        summary: Get award details
        description: Get detailed information about a specific award
        operationId: getAward
        security:
          - BearerAuth: []
        parameters:
          - name: award
            in: path
            required: true
            schema:
              type: integer
            description: Award ID
        responses:
          "200":
            description: Award details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Award"
  
      put:
        tags:
          - Awards
        summary: Update award
        description: Update award information
        operationId: updateAward
        security:
          - BearerAuth: []
        parameters:
          - name: award
            in: path
            required: true
            schema:
              type: integer
            description: Award ID
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AwardRequest"
        responses:
          "200":
            description: Award updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Award"
  
      delete:
        tags:
          - Awards
        summary: Delete award
        description: Delete an award record
        operationId: deleteAward
        security:
          - BearerAuth: []
        parameters:
          - name: award
            in: path
            required: true
            schema:
              type: integer
            description: Award ID
        responses:
          "200":
            description: Award deleted successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: "Award deleted successfully"
  # from business.yaml
    /businesses:
      get:
        tags:
          - Businesses
        summary: List businesses
        description: Get paginated list of businesses
        operationId: listBusinesses
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
              default: 1
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
              default: 15
            description: Items per page
          - in: query
            name: search
            schema:
              type: string
            description: Search by business name, email, or phone
          - in: query
            name: include_inactive
            schema:
              type: boolean
              default: false
            description: Include businesses with inactive records
        responses:
          "200":
            description: List of businesses
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        items:
                          type: array
                          items:
                            $ref: "#/components/schemas/Business"
                        pagination:
                          $ref: "#/components/schemas/Pagination"
          "401":
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/UnauthorizedResponse"
  
      post:
        tags:
          - Businesses
        summary: Create business
        description: Create a new business
        operationId: createBusiness
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BusinessRequest"
        responses:
          "201":
            description: Business created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Business"
          "422":
            description: Validation error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/ValidationErrorResponse"
  
    /businesses/{business}:
      get:
        tags:
          - Businesses
        summary: Get business details
        description: Get detailed information about a specific business
        operationId: getBusiness
        security:
          - BearerAuth: []
        parameters:
          - name: business
            in: path
            required: true
            schema:
              type: integer
            description: Business ID
          - in: query
            name: include_history
            schema:
              type: boolean
              default: false
            description: Include historical data fields
        responses:
          "200":
            description: Business details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Business"
          "404":
            description: Business not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
          "401":
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/UnauthorizedResponse"
  
      put:
        tags:
          - Businesses
        summary: Update business
        description: Update business information
        operationId: updateBusiness
        security:
          - BearerAuth: []
        parameters:
          - name: business
            in: path
            required: true
            schema:
              type: integer
            description: Business ID
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BusinessRequest"
        responses:
          "200":
            description: Business updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Business"
          "404":
            description: Business not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
          "422":
            description: Validation error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/ValidationErrorResponse"
  
      delete:
        tags:
          - Businesses
        summary: Delete business
        description: Soft delete a business record
        operationId: deleteBusiness
        security:
          - BearerAuth: []
        parameters:
          - name: business
            in: path
            required: true
            schema:
              type: integer
            description: Business ID
        responses:
          "200":
            description: Business deleted successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: "Business deleted successfully"
          "404":
            description: Business not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
  
    # Historical Data Endpoints
    /businesses/{business}/history:
      get:
        tags:
          - Businesses
        summary: Get business history
        description: Get historical data for a business
        operationId: getBusinessHistory
        security:
          - BearerAuth: []
        parameters:
          - name: business
            in: path
            required: true
            schema:
              type: integer
            description: Business ID
          - in: query
            name: field
            schema:
              type: string
              enum: [name, email, phone, address, note]
            description: Filter by specific field type
          - in: query
            name: from_date
            schema:
              type: string
              format: date
            description: Filter history from this date
          - in: query
            name: to_date
            schema:
              type: string
              format: date
            description: Filter history to this date
        responses:
          "200":
            description: Business historical data
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        business_id:
                          type: integer
                          example: 1
                        name_history:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                              first_name:
                                type: string
                              last_name:
                                type: string
                              legal_name:
                                type: string
                              start_date:
                                type: string
                                format: date
                              end_date:
                                type: string
                                format: date
                                nullable: true
                              active:
                                type: boolean
                        email_history:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                              address:
                                type: string
                              start_date:
                                type: string
                                format: date
                              end_date:
                                type: string
                                format: date
                                nullable: true
                              active:
                                type: boolean
                        phone_history:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                              number:
                                type: string
                              start_date:
                                type: string
                                format: date
                              end_date:
                                type: string
                                format: date
                                nullable: true
                              active:
                                type: boolean
  # from documents.yaml
    /document-templates:
      get:
        tags:
          - Document Templates
        summary: List document templates
        description: Get paginated list of document templates
        operationId: listDocumentTemplates
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
            description: Items per page
          - in: query
            name: search
            schema:
              type: string
            description: Search by title or content
          - in: query
            name: status
            schema:
              type: string
              enum: [draft, published]
            description: Filter by status
        responses:
          "200":
            description: List of document templates
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: array
                      items:
                        $ref: "#/components/schemas/Document"
                    meta:
                      $ref: "#/components/schemas/Pagination"
  
      post:
        tags:
          - Document Templates
        summary: Create document template
        description: Create a new document template with placeholders
        operationId: createDocumentTemplate
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentRequest"
        responses:
          "201":
            description: Document template created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Document"
          "422":
            description: Validation error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/ValidationErrorResponse"
  
    /document-templates/{document}:
      get:
        tags:
          - Document Templates
        summary: Get document template details
        description: Get detailed information about a specific document template
        operationId: getDocumentTemplate
        security:
          - BearerAuth: []
        parameters:
          - name: document
            in: path
            required: true
            schema:
              type: integer
            description: Document template ID
        responses:
          "200":
            description: Document template details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Document"
          "404":
            description: Document template not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
  
      put:
        tags:
          - Document Templates
        summary: Update document template
        description: |
          Update document template. Creates a new version (SCD Type 2) automatically when content, title, or status changes.
          This ensures that existing document records continue to reference the template version they were created with.
        operationId: updateDocumentTemplate
        security:
          - BearerAuth: []
        parameters:
          - name: document
            in: path
            required: true
            schema:
              type: integer
            description: Document template ID
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentRequest"
        responses:
          "200":
            description: Document template updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Document"
          "404":
            description: Document template not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
          "422":
            description: Validation error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/ValidationErrorResponse"
  
      delete:
        tags:
          - Document Templates
        summary: Delete document template
        description: Delete a document template. Cannot delete if it has associated document records.
        operationId: deleteDocumentTemplate
        security:
          - BearerAuth: []
        parameters:
          - name: document
            in: path
            required: true
            schema:
              type: integer
            description: Document template ID
        responses:
          "204":
            description: Document template deleted successfully
          "404":
            description: Document template not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
          "409":
            description: Conflict - Cannot delete document template with associated records
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    error:
                      type: object
                      properties:
                        code:
                          type: string
                          example: "CONFLICT"
                        message:
                          type: string
                          example: "Cannot delete document template that has associated records"
  
    /document-templates/placeholders:
      get:
        tags:
          - Document Templates
        summary: List available placeholders
        description: Get a list of all available placeholders that can be used in document templates. Placeholders are generated dynamically from API Resources.
        operationId: listPlaceholders
        security:
          - BearerAuth: []
        responses:
          "200":
            description: List of available placeholders
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: array
                      items:
                        $ref: "#/components/schemas/Placeholder"
  
    /document-templates/{document}/placeholders:
      get:
        tags:
          - Document Templates
        summary: Get document placeholders
        description: Get placeholders extracted from a specific document template's content
        operationId: getDocumentPlaceholders
        security:
          - BearerAuth: []
        parameters:
          - name: document
            in: path
            required: true
            schema:
              type: integer
            description: Document template ID
        responses:
          "200":
            description: Document placeholders
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: array
                      items:
                        $ref: "#/components/schemas/Placeholder"
  
    /document-records:
      get:
        tags:
          - Document Templates
        summary: List document records
        description: Get paginated list of document records (instances of document templates with data)
        operationId: listDocumentRecords
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
            description: Items per page
          - in: query
            name: document_id
            schema:
              type: integer
            description: Filter by document template ID
          - in: query
            name: is_current
            schema:
              type: boolean
            description: Filter by current version
          - in: query
            name: version_number
            schema:
              type: integer
            description: Filter by version number
        responses:
          "200":
            description: List of document records
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: array
                      items:
                        $ref: "#/components/schemas/DocumentRecord"
                    meta:
                      type: object
                      properties:
                        current_page:
                          type: integer
                        last_page:
                          type: integer
                        per_page:
                          type: integer
                        total:
                          type: integer
  
      post:
        tags:
          - Document Templates
        summary: Create document record
        description: Create a new document record (instance of a document template with data). Creates a new version if a current record exists, preserving history.
        operationId: createDocumentRecord
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentRecordRequest"
        responses:
          "201":
            description: Document record created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/DocumentRecord"
          "422":
            description: Validation error or missing required placeholders
            content:
              application/json:
                schema:
                  oneOf:
                    - $ref: "#/components/schemas/ValidationErrorResponse"
                    - type: object
                      properties:
                        error:
                          type: object
                          properties:
                            code:
                              type: string
                              example: "VALIDATION_ERROR"
                            message:
                              type: string
                              example: "Missing required placeholders"
                            details:
                              type: object
                              properties:
                                missing_placeholders:
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    ["People.first_name", "People.last_name"]
  
    /document-records/{document_record}:
      get:
        tags:
          - Document Templates
        summary: Get document record details
        description: Get detailed information about a specific document record
        operationId: getDocumentRecord
        security:
          - BearerAuth: []
        parameters:
          - name: document_record
            in: path
            required: true
            schema:
              type: integer
            description: Document record ID
        responses:
          "200":
            description: Document record details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/DocumentRecord"
          "404":
            description: Document record not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
  
      put:
        tags:
          - Document Templates
        summary: Update document record
        description: |
          Update document record. Creates a new version, preserving history of previous versions.
          
          **Restrictions:**
          - Cannot update a finalized document record (is_finalized = true)
          - If the record is finalized, the request will return a 403 Forbidden error
        operationId: updateDocumentRecord
        security:
          - BearerAuth: []
        parameters:
          - name: document_record
            in: path
            required: true
            schema:
              type: integer
            description: Document record ID
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentRecordRequest"
        responses:
          "200":
            description: Document record updated successfully (new version created)
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/DocumentRecord"
          "403":
            description: Document record is finalized and cannot be updated
          "404":
            description: Document record not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
          "422":
            description: Validation error or missing required placeholders
            content:
              application/json:
                schema:
                  oneOf:
                    - $ref: "#/components/schemas/ValidationErrorResponse"
                    - type: object
                      properties:
                        error:
                          type: object
                          properties:
                            code:
                              type: string
                              example: "VALIDATION_ERROR"
                            message:
                              type: string
                              example: "Missing required placeholders"
                            details:
                              type: object
                              properties:
                                missing_placeholders:
                                  type: array
                                  items:
                                    type: string
  
      delete:
        tags:
          - Document Templates
        summary: Delete document record
        description: Delete a document record
        operationId: deleteDocumentRecord
        security:
          - BearerAuth: []
        parameters:
          - name: document_record
            in: path
            required: true
            schema:
              type: integer
            description: Document record ID
        responses:
          "204":
            description: Document record deleted successfully
          "404":
            description: Document record not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
  # from email-managements.yaml
    /email-managements:
      get:
        tags:
          - Email Management
        summary: List email managements
        description: Get paginated list of email managements
        operationId: listEmailManagements
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
            description: Items per page
        responses:
          "200":
            description: List of email managements
  
      post:
        tags:
          - Email Management
        summary: Create email management
        operationId: createEmailManagement
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailManagementRequest"
        responses:
          "201":
            description: Email management created successfully
  
    /email-managements/{email_management}:
      get:
        tags:
          - Email Management
        summary: Get email management details
        operationId: getEmailManagement
        security:
          - BearerAuth: []
        parameters:
          - name: email_management
            in: path
            required: true
            schema:
              type: integer
        responses:
          "200":
            description: Email management details
  
      put:
        tags:
          - Email Management
        summary: Update email management
        operationId: updateEmailManagement
        security:
          - BearerAuth: []
        parameters:
          - name: email_management
            in: path
            required: true
            schema:
              type: integer
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailManagementRequest"
        responses:
          "200":
            description: Email management updated successfully
  
      delete:
        tags:
          - Email Management
        summary: Delete email management
        operationId: deleteEmailManagement
        security:
          - BearerAuth: []
        parameters:
          - name: email_management
            in: path
            required: true
            schema:
              type: integer
        responses:
          "200":
            description: Email management deleted successfully
  # from emails.yaml
    /emails:
      get:
        tags:
          - Emails
        summary: List emails
        description: Get paginated list of email addresses
        operationId: listEmails
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
            description: Items per page
          - in: query
            name: search
            schema:
              type: string
            description: Search by email address
          - in: query
            name: type
            schema:
              type: string
              enum: [personal, work, other]
            description: Filter by email type
        responses:
          "200":
            description: List of emails
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        items:
                          type: array
                          items:
                            $ref: "#/components/schemas/Email"
                        pagination:
                          $ref: "#/components/schemas/Pagination"
  
      post:
        tags:
          - Emails
        summary: Create email
        description: Create a new email address record
        operationId: createEmail
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailRequest"
        responses:
          "201":
            description: Email created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Email"
  
    /emails/{email}:
      get:
        tags:
          - Emails
        summary: Get email details
        description: Get detailed information about a specific email address
        operationId: getEmail
        security:
          - BearerAuth: []
        parameters:
          - name: email
            in: path
            required: true
            schema:
              type: integer
            description: Email ID
        responses:
          "200":
            description: Email details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Email"
  
      put:
        tags:
          - Emails
        summary: Update email
        description: Update email address information
        operationId: updateEmail
        security:
          - BearerAuth: []
        parameters:
          - name: email
            in: path
            required: true
            schema:
              type: integer
            description: Email ID
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailRequest"
        responses:
          "200":
            description: Email updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Email"
  
      delete:
        tags:
          - Emails
        summary: Delete email
        description: Delete an email address record
        operationId: deleteEmail
        security:
          - BearerAuth: []
        parameters:
          - name: email
            in: path
            required: true
            schema:
              type: integer
            description: Email ID
        responses:
          "200":
            description: Email deleted successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: "Email deleted successfully"
  # from organisations.yaml
    /organisations:
      get:
        tags:
          - Organisations
        summary: List organisations
        description: Get paginated list of organisations
        operationId: listOrganisations
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
            description: Items per page
          - in: query
            name: search
            schema:
              type: string
            description: Search by organisation name
          - in: query
            name: type
            schema:
              type: string
              enum: [company, department, division, other]
            description: Filter by organisation type
        responses:
          "200":
            description: List of organisations
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        items:
                          type: array
                          items:
                            $ref: "#/components/schemas/Organisation"
                        pagination:
                          $ref: "#/components/schemas/Pagination"
  
      post:
        tags:
          - Organisations
        summary: Create organisation
        description: Create a new organisation record
        operationId: createOrganisation
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganisationRequest"
        responses:
          "201":
            description: Organisation created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Organisation"
  
    /organisations/{organisation}:
      get:
        tags:
          - Organisations
        summary: Get organisation details
        description: Get detailed information about a specific organisation
        operationId: getOrganisation
        security:
          - BearerAuth: []
        parameters:
          - name: organisation
            in: path
            required: true
            schema:
              type: integer
            description: Organisation ID
        responses:
          "200":
            description: Organisation details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Organisation"
  
      put:
        tags:
          - Organisations
        summary: Update organisation
        description: Update organisation information
        operationId: updateOrganisation
        security:
          - BearerAuth: []
        parameters:
          - name: organisation
            in: path
            required: true
            schema:
              type: integer
            description: Organisation ID
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganisationRequest"
        responses:
          "200":
            description: Organisation updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Organisation"
  
      delete:
        tags:
          - Organisations
        summary: Delete organisation
        description: Delete an organisation record
        operationId: deleteOrganisation
        security:
          - BearerAuth: []
        parameters:
          - name: organisation
            in: path
            required: true
            schema:
              type: integer
            description: Organisation ID
        responses:
          "200":
            description: Organisation deleted successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: "Organisation deleted successfully"
  # from people.yaml
    /people:
      get:
        tags:
          - People Management
        summary: List people
        operationId: listPeople
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            example: 1
          - in: query
            name: per_page
            schema:
              type: integer
            example: 15
          - in: query
            name: search
            schema:
              type: string
          - in: query
            name: status
            schema:
              type: string
              enum: [active, inactive, terminated]
        responses:
          "200":
            description: List of people
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: array
                      items:
                        $ref: "#/components/schemas/Person"
                    pagination:
                      $ref: "#/components/schemas/Pagination"
          "401":
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/UnauthorizedResponse"
  
      post:
        tags:
          - People Management
        summary: Create person
        operationId: createPerson
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonRequest"
        responses:
          "201":
            description: Person created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Person"
          "422":
            description: Validation error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/ValidationErrorResponse"
  
    /people/{person}:
      get:
        tags:
          - People Management
        summary: Get person details
        operationId: getPerson
        security:
          - BearerAuth: []
        parameters:
          - name: person
            in: path
            required: true
            schema:
              type: integer
        responses:
          "200":
            description: Person details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Person"
          "404":
            description: Not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
  
      put:
        tags:
          - People Management
        summary: Update person
        operationId: updatePerson
        security:
          - BearerAuth: []
        parameters:
          - name: person
            in: path
            required: true
            schema:
              type: integer
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonRequest"
        responses:
          "200":
            description: Person updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Person"
          "404":
            description: Not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
  
      delete:
        tags:
          - People Management
        summary: Delete person
        operationId: deletePerson
        security:
          - BearerAuth: []
        parameters:
          - name: person
            in: path
            required: true
            schema:
              type: integer
        responses:
          "204":
            description: Person deleted successfully
          "404":
            description: Not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
  
    /people/{person}/profile:
      get:
        tags:
          - People Management
        summary: Get person profile
        operationId: getPersonProfile
        security:
          - BearerAuth: []
        parameters:
          - name: person
            in: path
            required: true
            schema:
              type: integer
        responses:
          "200":
            description: Person profile
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/PersonProfile"
          "404":
            description: Not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
  
      put:
        tags:
          - People Management
        summary: Update person profile
        operationId: updatePersonProfile
        security:
          - BearerAuth: []
        parameters:
          - name: person
            in: path
            required: true
            schema:
              type: integer
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonProfileRequest"
        responses:
          "200":
            description: Profile updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/PersonProfile"
          "404":
            description: Not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/NotFoundResponse"
  # from phones.yaml
    /phones:
      get:
        tags:
          - Phones
        summary: List phones
        description: Get paginated list of phone numbers
        operationId: listPhones
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
            description: Items per page
          - in: query
            name: search
            schema:
              type: string
            description: Search by phone number
          - in: query
            name: type
            schema:
              type: string
              enum: [mobile, home, work, fax, other]
            description: Filter by phone type
        responses:
          "200":
            description: List of phones
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        items:
                          type: array
                          items:
                            $ref: "#/components/schemas/Phone"
                        pagination:
                          $ref: "#/components/schemas/Pagination"
  
      post:
        tags:
          - Phones
        summary: Create phone
        description: Create a new phone number record
        operationId: createPhone
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PhoneRequest"
        responses:
          "201":
            description: Phone created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Phone"
  
    /phones/{phone}:
      get:
        tags:
          - Phones
        summary: Get phone details
        description: Get detailed information about a specific phone number
        operationId: getPhone
        security:
          - BearerAuth: []
        parameters:
          - name: phone
            in: path
            required: true
            schema:
              type: integer
            description: Phone ID
        responses:
          "200":
            description: Phone details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Phone"
  
      put:
        tags:
          - Phones
        summary: Update phone
        description: Update phone number information
        operationId: updatePhone
        security:
          - BearerAuth: []
        parameters:
          - name: phone
            in: path
            required: true
            schema:
              type: integer
            description: Phone ID
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PhoneRequest"
        responses:
          "200":
            description: Phone updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/Phone"
  
      delete:
        tags:
          - Phones
        summary: Delete phone
        description: Delete a phone number record
        operationId: deletePhone
        security:
          - BearerAuth: []
        parameters:
          - name: phone
            in: path
            required: true
            schema:
              type: integer
            description: Phone ID
        responses:
          "200":
            description: Phone deleted successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: "Phone deleted successfully"
  # from user-management.yaml
    /user-management:
      get:
        tags:
          - Users
        summary: List users
        description: Get paginated list of users
        operationId: listUsers
        security:
          - BearerAuth: []
        parameters:
          - in: query
            name: page
            schema:
              type: integer
            description: Page number
          - in: query
            name: per_page
            schema:
              type: integer
            description: Items per page
          - in: query
            name: search
            schema:
              type: string
            description: Search by user name or email
        responses:
          "200":
            description: List of users
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      type: object
                      properties:
                        items:
                          type: array
                          items:
                            $ref: "#/components/schemas/User"
                        pagination:
                          $ref: "#/components/schemas/Pagination"
  
      post:
        tags:
          - Users
        summary: Create user
        description: Create a new user
        operationId: createUser
        security:
          - BearerAuth: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserRequest"
        responses:
          "201":
            description: User created successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/User"
  
    /user-management/{user}:
      get:
        tags:
          - Users
        summary: Get user details
        description: Get detailed information about a specific user
        operationId: getUser
        security:
          - BearerAuth: []
        parameters:
          - name: user
            in: path
            required: true
            schema:
              type: integer
            description: User ID
        responses:
          "200":
            description: User details
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/User"
  
      put:
        tags:
          - Users
        summary: Update user
        description: Update user information
        operationId: updateUser
        security:
          - BearerAuth: []
        parameters:
          - name: user
            in: path
            required: true
            schema:
              type: integer
            description: User ID
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserRequest"
        responses:
          "200":
            description: User updated successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    data:
                      $ref: "#/components/schemas/User"
  
      delete:
        tags:
          - Users
        summary: Delete user
        description: Delete a user record
        operationId: deleteUser
        security:
          - BearerAuth: []
        parameters:
          - name: user
            in: path
            required: true
            schema:
              type: integer
            description: User ID
        responses:
          "200":
            description: User deleted successfully
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    success:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: "User deleted successfully"