You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Note. It is a bit rich in context compared to Petstore. This OAS docs has bit of some of the components I find important to add. Please advice. Companion specs will be generated after this one is settled.
openapi: 3.2.0
info:
title: Flights API
summary: A sample Flights API to replace the Swagger Petstore
description: |
The **Flights API** is a reference API for demonstrating OpenAPI 3.2 features
and [Arazzo](https://spec.openapis.org/arazzo/v1.0.1.html) workflow orchestration.
It provides operations for searching flights, checking real-time status,
managing bookings, rebooking cancelled flights, and passenger management.
### Arazzo Workflow Support
This API is designed to be consumed by an Arazzo description that models the
*"check flight status → rebook if cancelled"* workflow. Key `operationId` values
are stable contracts for workflow step references.
### Authentication
Use the `api_key` header or OAuth 2.0 bearer token for authenticated endpoints.
For testing, you can use the API key `demo-key-flights-2026`.
version: 1.0.0
termsOfService: https://flights-api.example.com/terms
contact:
name: Flights API Team
email: api-team@flights-api.example.com
url: https://flights-api.example.com/support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
description: Flights API Developer Portal
url: https://flights-api.example.com/docs
servers:
- url: https://api.flights-api.example.com/v1
description: Production
- url: https://sandbox.flights-api.example.com/v1
description: Sandbox – free to experiment, data resets nightly
tags:
- name: flights
summary: Flights
description: Search for flights and retrieve real-time flight status.
externalDocs:
description: Flight data sources
url: https://flights-api.example.com/docs/flights
- name: bookings
summary: Bookings
description: Create, retrieve, cancel, and rebook flight bookings.
externalDocs:
description: Booking lifecycle guide
url: https://flights-api.example.com/docs/bookings
- name: passengers
summary: Passengers
description: Manage passenger profiles and retrieve passenger details.
externalDocs:
description: Passenger data guide
url: https://flights-api.example.com/docs/passengers
# ---------------------------------------------------------------------------
# Paths
# ---------------------------------------------------------------------------
paths:
# ==========================================================================
# Flights
# ==========================================================================
/flights:
get:
operationId: searchFlights
tags:
- flights
summary: Search flights
description: |
Search for available flights by origin, destination, and departure date.
Returns a paginated list of matching flights.
parameters:
- $ref: '#/components/parameters/OriginQuery'
- $ref: '#/components/parameters/DestinationQuery'
- $ref: '#/components/parameters/DepartureDateQuery'
- $ref: '#/components/parameters/LimitQuery'
- $ref: '#/components/parameters/OffsetQuery'
responses:
'200':
description: A paginated list of flights matching the search criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/FlightSearchResults'
examples:
twoFlights:
$ref: '#/components/examples/FlightSearchResultsExample'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- api_key: []
- oauth2: [read:flights]
/flights/{flightId}:
get:
operationId: getFlightById
tags:
- flights
summary: Get flight details
description: Retrieve full details for a specific flight by its unique identifier.
parameters:
- $ref: '#/components/parameters/FlightIdPath'
responses:
'200':
description: Flight details.
content:
application/json:
schema:
$ref: '#/components/schemas/Flight'
examples:
scheduledFlight:
$ref: '#/components/examples/FlightScheduledExample'
cancelledFlight:
$ref: '#/components/examples/FlightCancelledExample'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- api_key: []
- oauth2: [read:flights]
/flights/{flightId}/status:
get:
operationId: getFlightStatus
tags:
- flights
summary: Get flight status
description: |
Retrieve the real-time status of a specific flight.
This is the primary entry point for the Arazzo *check-and-rebook* workflow.
parameters:
- $ref: '#/components/parameters/FlightIdPath'
responses:
'200':
description: Current flight status.
content:
application/json:
schema:
$ref: '#/components/schemas/FlightStatus'
examples:
onTime:
$ref: '#/components/examples/FlightStatusOnTimeExample'
cancelled:
$ref: '#/components/examples/FlightStatusCancelledExample'
delayed:
$ref: '#/components/examples/FlightStatusDelayedExample'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- api_key: []
- oauth2: [read:flights]
# ==========================================================================
# Bookings
# ==========================================================================
/bookings:
post:
operationId: createBooking
tags:
- bookings
summary: Create a booking
description: |
Book one or more passengers on a specific flight.
Returns the newly created booking with a confirmation number.
requestBody:
$ref: '#/components/requestBodies/CreateBookingBody'
responses:
'201':
description: Booking created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
examples:
newBooking:
$ref: '#/components/examples/BookingConfirmedExample'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- oauth2: [write:bookings]
/bookings/{bookingId}:
get:
operationId: getBookingById
tags:
- bookings
summary: Get booking details
description: Retrieve a booking by its unique identifier or confirmation number.
parameters:
- $ref: '#/components/parameters/BookingIdPath'
responses:
'200':
description: Booking details.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
examples:
confirmedBooking:
$ref: '#/components/examples/BookingConfirmedExample'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- api_key: []
- oauth2: [read:bookings]
delete:
operationId: cancelBooking
tags:
- bookings
summary: Cancel a booking
description: |
Cancel an existing booking. The booking status transitions to `cancelled`.
Cancellation policies and refund eligibility depend on fare class.
parameters:
- $ref: '#/components/parameters/BookingIdPath'
responses:
'200':
description: Booking cancelled successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
examples:
cancelledBooking:
$ref: '#/components/examples/BookingCancelledExample'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- oauth2: [write:bookings]
/bookings/{bookingId}/rebook:
post:
operationId: rebookFlight
tags:
- bookings
summary: Rebook a cancelled or disrupted flight
description: |
Rebook passengers from a cancelled or disrupted flight onto an alternative flight.
The original booking must have a status of `cancelled` or be linked to a flight
whose status is `cancelled` or `diverted`.
This is the second step in the Arazzo *check-and-rebook* workflow.
parameters:
- $ref: '#/components/parameters/BookingIdPath'
requestBody:
$ref: '#/components/requestBodies/RebookBody'
responses:
'201':
description: Rebooked successfully – new booking created.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
examples:
rebookedBooking:
$ref: '#/components/examples/BookingRebookedExample'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- oauth2: [write:bookings]
/bookings/{bookingId}/payment:
post:
operationId: processPayment
tags:
- bookings
summary: Process payment for a booking
description: |
Submit payment for an unpaid or partially paid booking.
Supports credit card and voucher payment methods.
parameters:
- $ref: '#/components/parameters/BookingIdPath'
requestBody:
$ref: '#/components/requestBodies/PaymentBody'
responses:
'200':
description: Payment processed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentReceipt'
examples:
paidReceipt:
$ref: '#/components/examples/PaymentReceiptExample'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- oauth2: [write:bookings]
# ==========================================================================
# Passengers
# ==========================================================================
/passengers:
post:
operationId: createPassenger
tags:
- passengers
summary: Create a passenger profile
description: Register a new passenger profile for use in bookings.
requestBody:
$ref: '#/components/requestBodies/CreatePassengerBody'
responses:
'201':
description: Passenger profile created.
content:
application/json:
schema:
$ref: '#/components/schemas/Passenger'
examples:
newPassenger:
$ref: '#/components/examples/PassengerExample'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- oauth2: [write:passengers]
/passengers/{passengerId}:
get:
operationId: getPassengerById
tags:
- passengers
summary: Get passenger details
description: Retrieve a passenger profile by its unique identifier.
parameters:
- $ref: '#/components/parameters/PassengerIdPath'
responses:
'200':
description: Passenger profile.
content:
application/json:
schema:
$ref: '#/components/schemas/Passenger'
examples:
existingPassenger:
$ref: '#/components/examples/PassengerExample'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- api_key: []
- oauth2: [read:passengers]
put:
operationId: updatePassenger
tags:
- passengers
summary: Update a passenger profile
description: Replace an existing passenger profile with the provided data.
parameters:
- $ref: '#/components/parameters/PassengerIdPath'
requestBody:
$ref: '#/components/requestBodies/CreatePassengerBody'
responses:
'200':
description: Passenger profile updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Passenger'
examples:
updatedPassenger:
$ref: '#/components/examples/PassengerExample'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- oauth2: [write:passengers]
delete:
operationId: deletePassenger
tags:
- passengers
summary: Delete a passenger profile
description: |
Remove a passenger profile. Existing bookings referencing this passenger
are not affected.
parameters:
- $ref: '#/components/parameters/PassengerIdPath'
responses:
'200':
description: Passenger profile deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
examples:
deleted:
summary: Passenger deleted
value:
code: 200
type: success
message: Passenger pax-101 deleted successfully
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- oauth2: [write:passengers]
# ---------------------------------------------------------------------------
# Components
# ---------------------------------------------------------------------------
components:
# ==========================================================================
# Schemas
# ==========================================================================
schemas:
# --- Core domain objects ------------------------------------------------
Flight:
type: object
description: A commercial flight between two airports, including schedule, status, aircraft assignment, and available fare classes.
required:
- flightId
- flightNumber
- airline
- origin
- destination
- scheduledDeparture
- scheduledArrival
- status
properties:
flightId:
type: string
description: Unique flight identifier.
examples:
- fl-8840
flightNumber:
type: string
description: IATA flight number.
examples:
- DL-1024
airline:
$ref: '#/components/schemas/Airline'
origin:
$ref: '#/components/schemas/Airport'
destination:
$ref: '#/components/schemas/Airport'
scheduledDeparture:
type: string
format: date-time
description: Scheduled departure time (ISO 8601).
examples:
- '2026-06-15T08:30:00Z'
scheduledArrival:
type: string
format: date-time
description: Scheduled arrival time (ISO 8601).
examples:
- '2026-06-15T11:45:00Z'
actualDeparture:
type: string
format: date-time
description: Actual departure time, if departed.
actualArrival:
type: string
format: date-time
description: Actual arrival time, if arrived.
status:
$ref: '#/components/schemas/FlightStatusEnum'
aircraft:
$ref: '#/components/schemas/Aircraft'
fareClasses:
type: array
description: Available fare classes and pricing.
items:
$ref: '#/components/schemas/FareClass'
FlightStatus:
type: object
description: Real-time operational status of a flight, including delay information, gate assignment, and cancellation details when applicable.
required:
- flightId
- flightNumber
- status
- updatedAt
properties:
flightId:
type: string
examples:
- fl-8840
flightNumber:
type: string
examples:
- DL-1024
status:
$ref: '#/components/schemas/FlightStatusEnum'
delayMinutes:
type: integer
format: int32
description: Delay in minutes (0 if on time, null if cancelled).
examples:
- 0
cancellationReason:
type: string
description: Reason for cancellation, if applicable.
examples:
- Severe weather at destination airport
gate:
type: string
description: Departure gate.
examples:
- B42
terminal:
type: string
description: Departure terminal.
examples:
- T-South
updatedAt:
type: string
format: date-time
description: Timestamp of the last status update.
examples:
- '2026-06-15T07:55:00Z'
FlightStatusEnum:
type: string
description: Current operational status of the flight.
enum:
- scheduled
- on_time
- delayed
- boarding
- departed
- in_air
- landed
- arrived
- cancelled
- diverted
examples:
- on_time
FlightSearchResults:
type: object
description: Paginated response containing flights matching the search criteria.
required:
- data
- pagination
properties:
data:
type: array
items:
$ref: '#/components/schemas/Flight'
pagination:
$ref: '#/components/schemas/Pagination'
Airline:
type: object
description: An airline carrier identified by its IATA code and display name.
required:
- code
- name
properties:
code:
type: string
description: IATA airline code.
examples:
- DL
name:
type: string
description: Airline display name.
examples:
- Delta Air Lines
Airport:
type: object
description: An airport identified by its IATA code, including city, country, and timezone information.
required:
- iataCode
- name
- city
properties:
iataCode:
type: string
description: IATA airport code.
examples:
- ATL
name:
type: string
description: Airport name.
examples:
- Hartsfield-Jackson Atlanta International Airport
city:
type: string
examples:
- Atlanta
country:
type: string
examples:
- US
timezone:
type: string
description: IANA timezone identifier.
examples:
- America/New_York
Aircraft:
type: object
description: An aircraft assigned to a flight, identified by model and registration number.
properties:
model:
type: string
examples:
- Boeing 737-900ER
registration:
type: string
examples:
- N801DZ
FareClass:
type: object
description: A fare class representing a cabin tier, booking code, price, and seat availability for a specific flight.
required:
- cabin
- code
- price
properties:
cabin:
type: string
enum:
- economy
- premium_economy
- business
- first
examples:
- economy
code:
type: string
description: Fare class letter code.
examples:
- Y
price:
$ref: '#/components/schemas/Money'
seatsAvailable:
type: integer
format: int32
examples:
- 42
Money:
type: object
description: A monetary amount with its ISO 4217 currency code. Used for pricing, payments, and refunds.
required:
- amount
- currency
properties:
amount:
type: number
format: double
examples:
- 349.99
currency:
type: string
description: ISO 4217 currency code.
examples:
- USD
# --- Booking objects ----------------------------------------------------
Booking:
type: object
description: A flight reservation linking one or more passengers to a specific flight, fare class, and payment. Tracks lifecycle from pending through confirmed, cancelled, rebooked, or completed.
required:
- bookingId
- confirmationNumber
- status
- flight
- passengers
- createdAt
properties:
bookingId:
type: string
examples:
- bk-220401
confirmationNumber:
type: string
description: Human-readable 6-character confirmation code.
examples:
- XKCD42
status:
$ref: '#/components/schemas/BookingStatusEnum'
flight:
$ref: '#/components/schemas/Flight'
passengers:
type: array
items:
$ref: '#/components/schemas/Passenger'
minItems: 1
fareClass:
$ref: '#/components/schemas/FareClass'
totalPrice:
$ref: '#/components/schemas/Money'
payment:
$ref: '#/components/schemas/PaymentSummary'
originalBookingId:
type: string
description: Reference to the original booking when this is a rebooking.
examples:
- bk-220400
createdAt:
type: string
format: date-time
examples:
- '2026-06-10T14:22:00Z'
updatedAt:
type: string
format: date-time
BookingStatusEnum:
type: string
description: Current status of the booking.
enum:
- pending
- confirmed
- cancelled
- rebooked
- completed
examples:
- confirmed
CreateBookingRequest:
type: object
description: Request payload for creating a new flight booking, specifying the flight, passengers, fare class, and optional seat preferences.
required:
- flightId
- passengerIds
- fareClassCode
properties:
flightId:
type: string
description: ID of the flight to book.
examples:
- fl-8840
passengerIds:
type: array
description: List of passenger IDs to include in the booking.
items:
type: string
minItems: 1
examples:
- - pax-101
- pax-102
fareClassCode:
type: string
description: Fare class code to book.
examples:
- Y
seatPreferences:
type: array
description: Optional seat preference per passenger.
items:
$ref: '#/components/schemas/SeatPreference'
SeatPreference:
type: object
description: A passenger's preferred seat position (window, middle, or aisle) for a booking.
properties:
passengerId:
type: string
examples:
- pax-101
preference:
type: string
enum:
- window
- middle
- aisle
examples:
- aisle
RebookRequest:
type: object
description: Request payload for rebooking passengers from a cancelled or disrupted flight onto an alternative flight.
required:
- newFlightId
properties:
newFlightId:
type: string
description: The alternative flight to rebook onto.
examples:
- fl-8841
fareClassCode:
type: string
description: Desired fare class on the new flight. Defaults to the original fare class.
examples:
- Y
reason:
type: string
description: Optional reason or note for the rebooking.
examples:
- Original flight DL-1024 cancelled due to weather
# --- Payment objects ----------------------------------------------------
PaymentRequest:
type: object
description: Request payload for processing a payment against a booking. Supports credit card and voucher payment methods.
required:
- method
- amount
properties:
method:
type: string
enum:
- credit_card
- voucher
examples:
- credit_card
amount:
$ref: '#/components/schemas/Money'
creditCard:
$ref: '#/components/schemas/CreditCard'
voucherCode:
type: string
description: Voucher code, required when method is `voucher`.
examples:
- REBK-CREDIT-5000
CreditCard:
type: object
description: Credit card details for payment processing. Only the last four digits are stored for security.
properties:
lastFourDigits:
type: string
examples:
- '4242'
brand:
type: string
enum:
- visa
- mastercard
- amex
- discover
examples:
- visa
expiryMonth:
type: integer
format: int32
examples:
- 12
expiryYear:
type: integer
format: int32
examples:
- 2028
PaymentSummary:
type: object
description: Summary of the payment state for a booking, including the total amount charged and payment method used.
properties:
status:
type: string
enum:
- unpaid
- paid
- partially_paid
- refunded
examples:
- paid
totalCharged:
$ref: '#/components/schemas/Money'
method:
type: string
examples:
- credit_card
PaymentReceipt:
type: object
description: Confirmation receipt returned after a payment is processed, including the transaction status and timestamp.
required:
- receiptId
- bookingId
- status
- amount
properties:
receiptId:
type: string
examples:
- rcpt-90210
bookingId:
type: string
examples:
- bk-220401
status:
type: string
enum:
- success
- failed
- pending
examples:
- success
amount:
$ref: '#/components/schemas/Money'
method:
type: string
examples:
- credit_card
processedAt:
type: string
format: date-time
examples:
- '2026-06-10T14:25:00Z'
# --- Passenger objects --------------------------------------------------
Passenger:
type: object
description: A passenger profile containing personal details, contact information, and optional loyalty program membership.
required:
- passengerId
- firstName
- lastName
- email
properties:
passengerId:
type: string
examples:
- pax-101
firstName:
type: string
examples:
- Ada
lastName:
type: string
examples:
- Lovelace
email:
type: string
format: email
examples:
- ada.lovelace@example.com
phone:
type: string
examples:
- '+14045551234'
dateOfBirth:
type: string
format: date
examples:
- '1990-05-15'
loyaltyNumber:
type: string
description: Frequent flyer / loyalty program number.
examples:
- DL-GOLD-99887766
createdAt:
type: string
format: date-time
examples:
- '2026-01-05T09:00:00Z'
CreatePassengerRequest:
type: object
description: Request payload for creating or updating a passenger profile. The passengerId is server-generated.
required:
- firstName
- lastName
- email
properties:
firstName:
type: string
examples:
- Ada
lastName:
type: string
examples:
- Lovelace
email:
type: string
format: email
examples:
- ada.lovelace@example.com
phone:
type: string
examples:
- '+14045551234'
dateOfBirth:
type: string
format: date
examples:
- '1990-05-15'
loyaltyNumber:
type: string
examples:
- DL-GOLD-99887766
# --- Shared / utility objects -------------------------------------------
Pagination:
type: object
description: Pagination metadata for list responses, providing total count and the current offset window.
required:
- total
- limit
- offset
properties:
total:
type: integer
format: int32
description: Total number of matching records.
examples:
- 42
limit:
type: integer
format: int32
examples:
- 20
offset:
type: integer
format: int32
examples:
- 0
ApiResponse:
type: object
description: Generic API response envelope used for operations that return a status message rather than a domain object.
properties:
code:
type: integer
format: int32
examples:
- 200
type:
type: string
examples:
- success
message:
type: string
examples:
- Operation completed successfully
Error:
type: object
description: Standardized error response returned for all 4xx and 5xx status codes, with an optional array of field-level details.
required:
- code
- type
- message
properties:
code:
type: integer
format: int32
examples:
- 400
type:
type: string
examples:
- validation_error
message:
type: string
examples:
- 'Invalid input: flightId is required'
details:
type: array
description: Optional field-level error details.
items:
$ref: '#/components/schemas/ErrorDetail'
ErrorDetail:
type: object
description: A single field-level validation error identifying which field failed and the specific issue.
properties:
field:
type: string
examples:
- flightId
issue:
type: string
examples:
- Field is required
# ==========================================================================
# Parameters
# ==========================================================================
parameters:
FlightIdPath:
name: flightId
in: path
required: true
description: Unique flight identifier.
schema:
type: string
examples:
default:
summary: A Delta flight
value: fl-8840
BookingIdPath:
name: bookingId
in: path
required: true
description: Unique booking identifier.
schema:
type: string
examples:
default:
summary: A confirmed booking
value: bk-220401
PassengerIdPath:
name: passengerId
in: path
required: true
description: Unique passenger identifier.
schema:
type: string
examples:
default:
summary: An existing passenger
value: pax-101
OriginQuery:
name: origin
in: query
required: true
description: IATA code of the departure airport.
schema:
type: string
examples:
atlanta:
summary: Atlanta
value: ATL
DestinationQuery:
name: destination
in: query
required: true
description: IATA code of the arrival airport.
schema:
type: string
examples:
lax:
summary: Los Angeles
value: LAX
DepartureDateQuery:
name: departureDate
in: query
required: true
description: Departure date (ISO 8601 date format).
schema:
type: string
format: date
examples:
summerDate:
summary: Summer 2026 date
value: '2026-06-15'
LimitQuery:
name: limit
in: query
required: false
description: Maximum number of results to return (default 20, max 100).
schema:
type: integer
format: int32
default: 20
minimum: 1
maximum: 100
OffsetQuery:
name: offset
in: query
required: false
description: Number of results to skip for pagination.
schema:
type: integer
format: int32
default: 0
minimum: 0
# ==========================================================================
# Request Bodies
# ==========================================================================
requestBodies:
CreateBookingBody:
description: Booking details for the new reservation.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBookingRequest'
examples:
singlePassenger:
summary: Single passenger booking
value:
flightId: fl-8840
passengerIds:
- pax-101
fareClassCode: Y
twoPassengers:
summary: Two passenger booking with seat preferences
value:
flightId: fl-8840
passengerIds:
- pax-101
- pax-102
fareClassCode: Y
seatPreferences:
- passengerId: pax-101
preference: aisle
- passengerId: pax-102
preference: window
RebookBody:
description: Details for rebooking onto an alternative flight.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RebookRequest'
examples:
weatherRebook:
summary: Rebook due to weather cancellation
value:
newFlightId: fl-8841
fareClassCode: Y
reason: Original flight DL-1024 cancelled due to weather
PaymentBody:
description: Payment details for the booking.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequest'
examples:
creditCardPayment:
summary: Pay with credit card
value:
method: credit_card
amount:
amount: 349.99
currency: USD
creditCard:
lastFourDigits: '4242'
brand: visa
expiryMonth: 12
expiryYear: 2028
voucherPayment:
summary: Pay with rebooking voucher
value:
method: voucher
amount:
amount: 349.99
currency: USD
voucherCode: REBK-CREDIT-5000
CreatePassengerBody:
description: Passenger profile information.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePassengerRequest'
examples:
newPassenger:
summary: Create passenger profile
value:
firstName: Ada
lastName: Lovelace
email: ada.lovelace@example.com
phone: '+14045551234'
dateOfBirth: '1990-05-15'
loyaltyNumber: DL-GOLD-99887766
# ==========================================================================
# Responses (reusable error responses)
# ==========================================================================
responses:
BadRequest:
description: The request is invalid or missing required parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missingField:
summary: Missing required field
value:
code: 400
type: validation_error
message: 'Invalid input: flightId is required'
details:
- field: flightId
issue: Field is required
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
flightNotFound:
summary: Flight not found
value:
code: 404
type: not_found
message: Flight fl-9999 not found
bookingNotFound:
summary: Booking not found
value:
code: 404
type: not_found
message: Booking bk-000000 not found
InternalServerError:
description: An unexpected error occurred on the server.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
serverError:
summary: Internal server error
value:
code: 500
type: internal_error
message: An unexpected error occurred. Please try again later.
# ==========================================================================
# Examples
# ==========================================================================
examples:
# --- Flight examples ----------------------------------------------------
FlightScheduledExample:
summary: A scheduled Delta flight ATL → LAX
value:
flightId: fl-8840
flightNumber: DL-1024
airline:
code: DL
name: Delta Air Lines
origin:
iataCode: ATL
name: Hartsfield-Jackson Atlanta International Airport
city: Atlanta
country: US
timezone: America/New_York
destination:
iataCode: LAX
name: Los Angeles International Airport
city: Los Angeles
country: US
timezone: America/Los_Angeles
scheduledDeparture: '2026-06-15T08:30:00Z'
scheduledArrival: '2026-06-15T11:45:00Z'
status: scheduled
aircraft:
model: Boeing 737-900ER
registration: N801DZ
fareClasses:
- cabin: economy
code: Y
price:
amount: 349.99
currency: USD
seatsAvailable: 42
- cabin: business
code: J
price:
amount: 1249.00
currency: USD
seatsAvailable: 8
FlightCancelledExample:
summary: A cancelled flight
value:
flightId: fl-8840
flightNumber: DL-1024
airline:
code: DL
name: Delta Air Lines
origin:
iataCode: ATL
name: Hartsfield-Jackson Atlanta International Airport
city: Atlanta
country: US
timezone: America/New_York
destination:
iataCode: LAX
name: Los Angeles International Airport
city: Los Angeles
country: US
timezone: America/Los_Angeles
scheduledDeparture: '2026-06-15T08:30:00Z'
scheduledArrival: '2026-06-15T11:45:00Z'
status: cancelled
aircraft:
model: Boeing 737-900ER
registration: N801DZ
FlightSearchResultsExample:
summary: Search results for ATL → LAX on 2026-06-15
value:
data:
- flightId: fl-8840
flightNumber: DL-1024
airline:
code: DL
name: Delta Air Lines
origin:
iataCode: ATL
name: Hartsfield-Jackson Atlanta International Airport
city: Atlanta
country: US
destination:
iataCode: LAX
name: Los Angeles International Airport
city: Los Angeles
country: US
scheduledDeparture: '2026-06-15T08:30:00Z'
scheduledArrival: '2026-06-15T11:45:00Z'
status: scheduled
fareClasses:
- cabin: economy
code: Y
price:
amount: 349.99
currency: USD
seatsAvailable: 42
- flightId: fl-8841
flightNumber: DL-1028
airline:
code: DL
name: Delta Air Lines
origin:
iataCode: ATL
name: Hartsfield-Jackson Atlanta International Airport
city: Atlanta
country: US
destination:
iataCode: LAX
name: Los Angeles International Airport
city: Los Angeles
country: US
scheduledDeparture: '2026-06-15T14:00:00Z'
scheduledArrival: '2026-06-15T17:15:00Z'
status: scheduled
fareClasses:
- cabin: economy
code: Y
price:
amount: 299.99
currency: USD
seatsAvailable: 67
pagination:
total: 2
limit: 20
offset: 0
# --- Flight status examples ---------------------------------------------
FlightStatusOnTimeExample:
summary: Flight is on time
value:
flightId: fl-8840
flightNumber: DL-1024
status: on_time
delayMinutes: 0
gate: B42
terminal: T-South
updatedAt: '2026-06-15T07:55:00Z'
FlightStatusCancelledExample:
summary: Flight is cancelled
value:
flightId: fl-8840
flightNumber: DL-1024
status: cancelled
delayMinutes: null
cancellationReason: Severe weather at destination airport
gate: B42
terminal: T-South
updatedAt: '2026-06-15T06:30:00Z'
FlightStatusDelayedExample:
summary: Flight is delayed
value:
flightId: fl-8840
flightNumber: DL-1024
status: delayed
delayMinutes: 45
gate: B42
terminal: T-South
updatedAt: '2026-06-15T07:45:00Z'
# --- Booking examples ---------------------------------------------------
BookingConfirmedExample:
summary: A confirmed booking
value:
bookingId: bk-220401
confirmationNumber: XKCD42
status: confirmed
flight:
flightId: fl-8840
flightNumber: DL-1024
airline:
code: DL
name: Delta Air Lines
origin:
iataCode: ATL
name: Hartsfield-Jackson Atlanta International Airport
city: Atlanta
country: US
destination:
iataCode: LAX
name: Los Angeles International Airport
city: Los Angeles
country: US
scheduledDeparture: '2026-06-15T08:30:00Z'
scheduledArrival: '2026-06-15T11:45:00Z'
status: scheduled
passengers:
- passengerId: pax-101
firstName: Ada
lastName: Lovelace
email: ada.lovelace@example.com
fareClass:
cabin: economy
code: Y
price:
amount: 349.99
currency: USD
totalPrice:
amount: 349.99
currency: USD
payment:
status: paid
totalCharged:
amount: 349.99
currency: USD
method: credit_card
createdAt: '2026-06-10T14:22:00Z'
BookingCancelledExample:
summary: A cancelled booking
value:
bookingId: bk-220401
confirmationNumber: XKCD42
status: cancelled
flight:
flightId: fl-8840
flightNumber: DL-1024
airline:
code: DL
name: Delta Air Lines
origin:
iataCode: ATL
name: Hartsfield-Jackson Atlanta International Airport
city: Atlanta
country: US
destination:
iataCode: LAX
name: Los Angeles International Airport
city: Los Angeles
country: US
scheduledDeparture: '2026-06-15T08:30:00Z'
scheduledArrival: '2026-06-15T11:45:00Z'
status: cancelled
passengers:
- passengerId: pax-101
firstName: Ada
lastName: Lovelace
email: ada.lovelace@example.com
fareClass:
cabin: economy
code: Y
price:
amount: 349.99
currency: USD
totalPrice:
amount: 349.99
currency: USD
payment:
status: refunded
totalCharged:
amount: 349.99
currency: USD
method: credit_card
createdAt: '2026-06-10T14:22:00Z'
updatedAt: '2026-06-15T06:35:00Z'
BookingRebookedExample:
summary: A rebooked booking (references original)
value:
bookingId: bk-220402
confirmationNumber: REBK77
status: confirmed
flight:
flightId: fl-8841
flightNumber: DL-1028
airline:
code: DL
name: Delta Air Lines
origin:
iataCode: ATL
name: Hartsfield-Jackson Atlanta International Airport
city: Atlanta
country: US
destination:
iataCode: LAX
name: Los Angeles International Airport
city: Los Angeles
country: US
scheduledDeparture: '2026-06-15T14:00:00Z'
scheduledArrival: '2026-06-15T17:15:00Z'
status: scheduled
passengers:
- passengerId: pax-101
firstName: Ada
lastName: Lovelace
email: ada.lovelace@example.com
fareClass:
cabin: economy
code: Y
price:
amount: 299.99
currency: USD
totalPrice:
amount: 0.00
currency: USD
payment:
status: paid
totalCharged:
amount: 0.00
currency: USD
method: voucher
originalBookingId: bk-220401
createdAt: '2026-06-15T06:40:00Z'
# --- Payment examples ---------------------------------------------------
PaymentReceiptExample:
summary: Successful credit card payment
value:
receiptId: rcpt-90210
bookingId: bk-220401
status: success
amount:
amount: 349.99
currency: USD
method: credit_card
processedAt: '2026-06-10T14:25:00Z'
# --- Passenger examples -------------------------------------------------
PassengerExample:
summary: A passenger profile
value:
passengerId: pax-101
firstName: Ada
lastName: Lovelace
email: ada.lovelace@example.com
phone: '+14045551234'
dateOfBirth: '1990-05-15'
loyaltyNumber: DL-GOLD-99887766
createdAt: '2026-01-05T09:00:00Z'
# ==========================================================================
# Security Schemes
# ==========================================================================
securitySchemes:
api_key:
type: apiKey
name: X-API-Key
in: header
description: |
API key for read-only access. For testing, use `demo-key-flights-2026`.
oauth2:
type: oauth2
description: OAuth 2.0 with authorization code flow for full access.
flows:
authorizationCode:
authorizationUrl: https://auth.flights-api.example.com/authorize
tokenUrl: https://auth.flights-api.example.com/token
scopes:
read:flights: Read flight information
read:bookings: Read booking details
write:bookings: Create, cancel, and rebook bookings
read:passengers: Read passenger profiles
write:passengers: Create and manage passenger profiles
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
-
Here is my initial stab at this.
Note. It is a bit rich in context compared to Petstore. This OAS docs has bit of some of the components I find important to add. Please advice. Companion specs will be generated after this one is settled.
Beta Was this translation helpful? Give feedback.
All reactions