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

paths:
  /calendar:
    get:
      tags: [Calendar]
      summary: List all calendar events
      parameters:
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: per_page
          schema: { type: integer, default: 20 }
        - in: query
          name: month
          schema: { type: integer }
        - in: query
          name: year
          schema: { type: integer }
      responses:
        "200": { description: Events retrieved successfully }
    post:
      tags: [Calendar]
      summary: Create new calendar event
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EventCreate' }
      responses:
        "201": { description: Event created }

  /calendar/{id}:
    get:
      tags: [Calendar]
      summary: Get event details by ID
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200": { description: Event retrieved }
        "404": { description: Event not found }
    put:
      tags: [Calendar]
      summary: Update an existing event
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EventUpdate' }
      responses:
        "200": { description: Event updated }
        "404": { description: Event not found }
        "422": { description: Validation error }
    delete:
      tags: [Calendar]
      summary: Delete an event
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200": { description: Event deleted }
        "404": { description: Event not found }

components:
  schemas:
    EventCreate:
      type: object
      required: [title, start_date]
      properties:
        title: { type: string }
        description: { type: string }
        start_date: { type: string, format: date }
        end_date: { type: string, format: date }
        location: { type: string }
    EventUpdate:
      type: object
      properties:
        title: { type: string }
        description: { type: string }
        start_date: { type: string, format: date }
        end_date: { type: string, format: date }
        location: { type: string }