openapi: 3.1.0
info:
  title: HR API
  version: "1.0.0"
  description: |
    Employee directory, departments, and reporting hierarchy.
    Returns personal data — apps that use it must show the personal-data banner.
servers:
  - url: /apis/hr

paths:
  /employees:
    get:
      summary: List employees
      operationId: listEmployees
      parameters:
        - name: department
          in: query
          schema: { type: string }
          example: Økonomi
        - name: activeOnly
          in: query
          schema: { type: boolean, default: true }
        - name: include
          in: query
          schema:
            type: string
            enum: [manager]
          description: When set to "manager", expands manager objects inline.
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
      responses:
        '200':
          description: Employees
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/Employee' }
                  total: { type: integer }
                  page: { type: integer }
                  pageSize: { type: integer }
              examples:
                default:
                  value:
                    items:
                      - id: emp-001
                        firstName: Alice
                        lastName: Andersen
                        email: alice@example.com
                        department: Økonomi
                        title: Senior Analyst
                        managerId: emp-010
                        active: true
                      - id: emp-002
                        firstName: Bob
                        lastName: Berg
                        email: bob@example.com
                        department: HR
                        title: HR Partner
                        managerId: emp-011
                        active: true
                      - id: emp-010
                        firstName: Camilla
                        lastName: Christensen
                        email: camilla@example.com
                        department: Økonomi
                        title: CFO
                        managerId: null
                        active: true
                    total: 3
                    page: 1
                    pageSize: 100

  /employees/{id}:
    get:
      summary: Get one employee
      operationId: getEmployee
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
          example: emp-001
      responses:
        '200':
          description: Employee
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Employee' }
              example:
                id: emp-001
                firstName: Alice
                lastName: Andersen
                email: alice@example.com
                department: Økonomi
                title: Senior Analyst
                managerId: emp-010
                active: true

  /departments:
    get:
      summary: List departments
      operationId: listDepartments
      responses:
        '200':
          description: Departments
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Department' }
              examples:
                default:
                  value:
                    - name: Økonomi
                      headcount: 12
                      manager: camilla@example.com
                    - name: HR
                      headcount: 5
                      manager: bob.manager@example.com
                    - name: IT
                      headcount: 18
                      manager: itlead@example.com
                    - name: Salg
                      headcount: 22
                      manager: sales.lead@example.com

components:
  schemas:
    Employee:
      type: object
      required: [id, firstName, lastName, email, department, title, active]
      properties:
        id: { type: string }
        firstName: { type: string }
        lastName: { type: string }
        email: { type: string, format: email }
        department: { type: string }
        title: { type: string }
        managerId:
          type: string
          nullable: true
        active: { type: boolean }
    Department:
      type: object
      required: [name, headcount]
      properties:
        name: { type: string }
        headcount: { type: integer }
        manager: { type: string, format: email }