openapi: 3.0.3
info:
  title: HR Management API
  description: >
    Human Resource Management System REST API.
    Covers employee lifecycle, payroll processing, and attendance tracking.
  version: 2.1.0
  contact:
    name: API Support Team
    email: api-support@company.com
  license:
    name: Proprietary

servers:
  - url: https://api.company.com/v1
    description: Production Server
  - url: https://staging-api.company.com/v1
    description: Staging Server

tags:
  - name: Employees
    description: Employee lifecycle operations
  - name: Payroll
    description: Payroll and compensation
  - name: Attendance
    description: Attendance and leave management

paths:
  /employees:
    get:
      summary: List all employees
      operationId: listEmployees
      tags: [Employees]
      parameters:
        - name: department
          in: query
          description: Filter by department code
          schema: { type: string }
        - name: isActive
          in: query
          schema: { type: boolean, default: true }
        - name: page
          in: query
          schema: { type: integer, default: 1, minimum: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        "200":
          description: Paginated list of employees
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmployeeListResponse"
        "401":
          description: Unauthorized
    post:
      summary: Create a new employee record
      operationId: createEmployee
      tags: [Employees]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmployeeCreate"
      responses:
        "201":
          description: Employee created
        "422":
          description: Validation error

  /employees/{employeeId}:
    get:
      summary: Get employee by ID
      operationId: getEmployee
      tags: [Employees]
      parameters:
        - name: employeeId
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Employee detail
        "404":
          description: Not found

  /payroll/run:
    post:
      summary: Trigger payroll processing
      operationId: runPayroll
      tags: [Payroll]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PayrollRunRequest"
      responses:
        "202":
          description: Payroll run accepted and queued

  /attendance/{employeeId}:
    get:
      summary: Get attendance records
      operationId: getAttendance
      tags: [Attendance]
      parameters:
        - name: employeeId
          in: path
          required: true
          schema: { type: integer }
        - name: month
          in: query
          required: true
          schema: { type: string, example: "2026-06" }
      responses:
        "200":
          description: Monthly attendance summary

components:
  schemas:
    Employee:
      type: object
      properties:
        employeeId:   { type: integer, readOnly: true }
        employeeCode: { type: string,  example: "EMP-00421" }
        fullName:     { type: string,  example: "Rajesh Kumar" }
        email:        { type: string,  format: email }
        designation:  { type: string,  example: "Senior Software Engineer" }
        department:   { type: string,  example: "Information Technology" }
        joinDate:     { type: string,  format: date }
        isActive:     { type: boolean }

    EmployeeCreate:
      type: object
      required: [fullName, email, department, designation]
      properties:
        fullName:    { type: string }
        email:       { type: string, format: email }
        designation: { type: string }
        department:  { type: string }
        joinDate:    { type: string, format: date }

    EmployeeListResponse:
      type: object
      properties:
        totalCount: { type: integer }
        page:       { type: integer }
        pageSize:   { type: integer }
        data:
          type: array
          items:
            $ref: "#/components/schemas/Employee"

    PayrollRunRequest:
      type: object
      required: [periodMonth, periodYear]
      properties:
        periodMonth:  { type: integer, minimum: 1, maximum: 12 }
        periodYear:   { type: integer, example: 2026 }
        includeBonus: { type: boolean, default: false }

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []