openapi: 3.0.3
info: { title: Purchase Order API, version: 1.0.0 }
servers: [ { url: https://your-domain.com/api/v1 } ]
tags: [ { name: Purchase Orders } ]
security: [ { bearerAuth: [] } ]

paths:
  /purchase-orders:
    get:
      tags: [Purchase Orders]
      summary: List purchase orders
      parameters:
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: per_page
          schema: { type: integer, default: 20 }
        - in: query
          name: q
          schema: { type: string, description: 'Search by PO number or supplier name' }
      responses:
        "200": { description: Purchase orders retrieved }
    post:
      tags: [Purchase Orders]
      summary: Create a purchase order with items
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [po_number, supplier_id, order_date, items]
              properties:
                po_number: { type: string }
                supplier_id: { type: integer }
                order_date: { type: string, format: date }
                expected_date: { type: string, format: date }
                status: { type: string, example: ordered }
                tax: { type: number, example: 0 }
                notes: { type: string }
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      supply_id: { type: integer, nullable: true }
                      description: { type: string }
                      quantity: { type: integer }
                      unit_cost: { type: number }
      responses:
        "201": { description: Purchase order created }

  /purchase-orders/{id}:
    get:
      tags: [Purchase Orders]
      summary: Get purchase order by ID
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200": { description: Purchase order with items }
        "404": { description: Not found }
    put:
      tags: [Purchase Orders]
      summary: Update purchase order status or dates
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string }
                expected_date: { type: string, format: date }
                notes: { type: string }
      responses:
        "200": { description: Purchase order updated }