openapi: 3.1.0
info:
  title: Support Tickets API
  version: "1.0.0"
  description: |
    Ticketing system for IT and HR helpdesks.
    Each user can see and modify only their own tickets (enforced by the backend
    based on the gateway-issued JWT). Field "assignee=me" expands to the calling user.
servers:
  - url: /apis/support-tickets

paths:
  /tickets:
    get:
      summary: List tickets
      operationId: listTickets
      parameters:
        - name: assignee
          in: query
          description: Use "me" for your own tickets. Otherwise an email.
          schema: { type: string }
          example: me
        - name: status
          in: query
          schema:
            type: string
            enum: [open, pending, resolved, closed]
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 10 }
      responses:
        '200':
          description: Tickets
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Ticket' }
              examples:
                default:
                  value:
                    - id: TKT-1042
                      title: Laptop won't connect to VPN
                      status: open
                      priority: high
                      createdAt: "2026-05-12T08:14:00Z"
                      assignee: alice@example.com
                      reporter: alice@example.com
                      category: it
                    - id: TKT-1041
                      title: Request new monitor
                      status: pending
                      priority: low
                      createdAt: "2026-05-09T13:22:00Z"
                      assignee: alice@example.com
                      reporter: alice@example.com
                      category: facilities
                    - id: TKT-1038
                      title: Onboarding for new hire May 20
                      status: open
                      priority: medium
                      createdAt: "2026-05-08T10:01:00Z"
                      assignee: bob@example.com
                      reporter: alice@example.com
                      category: hr
    post:
      summary: Create a ticket
      operationId: createTicket
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TicketCreate' }
            example:
              title: VPN issue
              priority: high
              category: it
              description: Can't connect to corporate VPN from home.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Ticket' }
              example:
                id: TKT-1043
                title: VPN issue
                status: open
                priority: high
                createdAt: "2026-05-14T09:00:00Z"
                assignee: itdesk@example.com
                reporter: alice@example.com
                category: it

  /tickets/{id}:
    get:
      summary: Get one ticket
      operationId: getTicket
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
          example: TKT-1042
      responses:
        '200':
          description: Ticket
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Ticket' }
              example:
                id: TKT-1042
                title: Laptop won't connect to VPN
                status: open
                priority: high
                createdAt: "2026-05-12T08:14:00Z"
                assignee: alice@example.com
                reporter: alice@example.com
                category: it
                description: VPN client says "auth failed" after entering MFA.

components:
  schemas:
    Ticket:
      type: object
      required: [id, title, status, priority, createdAt, assignee, reporter, category]
      properties:
        id: { type: string, example: TKT-1042 }
        title: { type: string }
        status:
          type: string
          enum: [open, pending, resolved, closed]
        priority:
          type: string
          enum: [low, medium, high, urgent]
        createdAt: { type: string, format: date-time }
        assignee: { type: string, format: email }
        reporter: { type: string, format: email }
        category:
          type: string
          enum: [it, hr, facilities, finance, other]
        description: { type: string }
    TicketCreate:
      type: object
      required: [title, priority, category]
      properties:
        title: { type: string }
        priority:
          type: string
          enum: [low, medium, high, urgent]
        category:
          type: string
          enum: [it, hr, facilities, finance, other]
        description: { type: string }