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

paths:
  /messages:
    get:
      tags: [Messages]
      summary: List user messages
      parameters:
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: per_page
          schema: { type: integer, default: 20 }
        - in: query
          name: type
          schema: { type: string, enum: [sent, received] }
        - in: query
          name: read
          schema: { type: boolean }
      responses:
        "200": { description: Messages retrieved }
    post:
      tags: [Messages]
      summary: Send a new message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [to, subject, body]
              properties:
                to: { type: integer, description: Recipient user ID }
                subject: { type: string }
                body: { type: string }
                priority: { type: string, enum: [low, normal, high], default: normal }
      responses:
        "201": { description: Message sent }

  /messages/{id}:
    get:
      tags: [Messages]
      summary: Get message by ID (auto-marks read if recipient)
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200": { description: Message retrieved }
        "404": { description: Not found }