3.2-query-example

JSON

{
  "openapi": "3.2.0",
  "info": {
    "title": "Flight API",
    "version": "1.0.0"
  },
  "paths": {
    "/flights/search": {
      "query": {
        "summary": "Search flights with complex criteria",
        "description": "Uses the HTTP QUERY method to perform a safe, idempotent flight search with filters that are too complex for a URL query string.",
        "operationId": "searchFlights",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "ATL"
                  },
                  "destination": {
                    "type": "string",
                    "example": "LHR"
                  },
                  "departureDate": {
                    "type": "string",
                    "format": "date",
                    "example": "2026-06-15"
                  },
                  "returnDate": {
                    "type": "string",
                    "format": "date",
                    "example": "2026-06-25"
                  },
                  "passengers": {
                    "type": "integer",
                    "minimum": 1,
                    "example": 2
                  },
                  "cabinClass": {
                    "type": "string",
                    "enum": [
                      "economy",
                      "premium-economy",
                      "business",
                      "first"
                    ],
                    "example": "business"
                  },
                  "nonStopOnly": {
                    "type": "boolean",
                    "example": true
                  }
                },
                "required": [
                  "origin",
                  "destination",
                  "departureDate"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matching flights",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "flights": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "flightNumber": {
                            "type": "string",
                            "example": "DL30"
                          },
                          "origin": {
                            "type": "string",
                            "example": "ATL"
                          },
                          "destination": {
                            "type": "string",
                            "example": "LHR"
                          },
                          "departureTime": {
                            "type": "string",
                            "format": "date-time",
                            "example": "2026-06-15T22:30:00Z"
                          },
                          "arrivalTime": {
                            "type": "string",
                            "format": "date-time",
                            "example": "2026-06-16T10:15:00Z"
                          },
                          "price": {
                            "type": "number",
                            "format": "float",
                            "example": 1249.99
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

YAML

openapi: 3.2.0
info:
  title: Flight API
  version: 1.0.0
  
  # The QUERY method is intended for safe, idempotent requests that still need a
  # request body, which makes it a good fit for flight search filters like dates,
  # cabin class, passenger count, and nonstop preferences. In practice, this is
  # clearer than forcing a long GET URL or misusing POST for a read-only search operation.

paths:
  /flights/search:
    query:
      summary: Search flights with complex criteria
      description: >
        Uses the HTTP QUERY method to perform a safe, idempotent flight search
        with filters that are too complex for a URL query string.
      operationId: searchFlights
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                origin:
                  type: string
                  example: ATL
                destination:
                  type: string
                  example: LHR
                departureDate:
                  type: string
                  format: date
                  example: 2026-06-15
                returnDate:
                  type: string
                  format: date
                  example: 2026-06-25
                passengers:
                  type: integer
                  minimum: 1
                  example: 2
                cabinClass:
                  type: string
                  enum: [economy, premium-economy, business, first]
                  example: business
                nonStopOnly:
                  type: boolean
                  example: true
              required:
                - origin
                - destination
                - departureDate
      responses:
        '200':
          description: Matching flights
          content:
            application/json:
              schema:
                type: object
                properties:
                  flights:
                    type: array
                    items:
                      type: object
                      properties:
                        flightNumber:
                          type: string
                          example: DL30
                        origin:
                          type: string
                          example: ATL
                        destination:
                          type: string
                          example: LHR
                        departureTime:
                          type: string
                          format: date-time
                          example: 2026-06-15T22:30:00Z
                        arrivalTime:
                          type: string
                          format: date-time
                          example: 2026-06-16T10:15:00Z
                        price:
                          type: number
                          format: float
                          example: 1249.99