Skip to content

Instantly share code, notes, and snippets.

@baywet

baywet/openapi-example-extended.yaml

Created April 29, 2026 13:55
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save baywet/3caafd66c9b431b0941c0354a5c145db to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save baywet/3caafd66c9b431b0941c0354a5c145db to your computer and use it in GitHub Desktop.
Download ZIP
Comparison of overlay reusable action target string interpolation support. The best way to look at this is to first diff the two descriptions to better understand that we're adding monitor endpoints for both creation operations. Then diff the overlays to understand the difference it makes when using string interpolation for the targets
Raw
openapi-example-extended.yaml
openapi: 3.2.0
info:
title: Payment Service API
version: 1.0.0
description: Simple API for order placement and wire transfers
paths:
/orders:
post:
operationId: place_order
summary: Place an order
description: Submit an order request and receive an order confirmation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
responses:
'200':
description: Order placed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResult'
'400':
description: Invalid request
/orders/{orderId}:
get:
operationId: monitor_order
summary: Monitor an order
description: Retrieve the current status and details of an order
parameters:
- name: orderId
in: path
required: true
description: The order identifier to monitor
schema:
type: string
responses:
'200':
description: Order details retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderMonitorResult'
'404':
description: Order not found
/transfers:
post:
operationId: wire_transfer
summary: Execute a wire transfer
description: Initiate a wire transfer and receive a confirmation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WireTransferRequest'
responses:
'200':
description: Wire transfer initiated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WireTransferResult'
'400':
description: Invalid request
/transfers/{transferId}:
get:
operationId: monitor_wire_transfer
summary: Monitor a wire transfer
description: Retrieve the current status and details of a wire transfer
parameters:
- name: transferId
in: path
required: true
description: The transfer identifier to monitor
schema:
type: string
responses:
'200':
description: Wire transfer details retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WireTransferMonitorResult'
'404':
description: Transfer not found
components:
schemas:
OrderRequest:
type: object
required:
- customerId
- items
- totalAmount
properties:
customerId:
type: string
description: Unique customer identifier
items:
type: array
items:
type: object
properties:
productId:
type: string
quantity:
type: integer
unitPrice:
type: number
totalAmount:
type: number
description: Total order amount in currency units
OrderResult:
type: object
properties:
orderId:
type: string
description: Unique order identifier
customerId:
type: string
status:
type: string
enum: [confirmed, pending, failed]
totalAmount:
type: number
timestamp:
type: string
format: date-time
OrderMonitorResult:
type: object
properties:
order:
$ref: '#/components/schemas/OrderResult'
lastUpdated:
type: string
format: date-time
trackingInfo:
type: string
WireTransferRequest:
type: object
required:
- fromAccount
- toAccount
- amount
- currency
properties:
fromAccount:
type: string
description: Source account number
toAccount:
type: string
description: Destination account number
amount:
type: number
description: Transfer amount
currency:
type: string
description: ISO 4217 currency code
referenceNumber:
type: string
description: Optional transfer reference
WireTransferResult:
type: object
properties:
transferId:
type: string
description: Unique transfer identifier
status:
type: string
enum: [completed, pending, failed]
amount:
type: number
currency:
type: string
executionTime:
type: string
format: date-time
errorMessage:
type: string
description: Error details if transfer failed
WireTransferMonitorResult:
type: object
properties:
transfer:
$ref: '#/components/schemas/WireTransferResult'
lastUpdated:
type: string
format: date-time
confirmationNumber:
type: string
Raw
openapi-example.yaml
openapi: 3.2.0
info:
title: Payment Service API
version: 1.0.0
description: Simple API for order placement and wire transfers
paths:
/orders:
post:
operationId: place_order
summary: Place an order
description: Submit an order request and receive an order confirmation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
responses:
'200':
description: Order placed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResult'
'400':
description: Invalid request
/transfers:
post:
operationId: wire_transfer
summary: Execute a wire transfer
description: Initiate a wire transfer and receive a confirmation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WireTransferRequest'
responses:
'200':
description: Wire transfer initiated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WireTransferResult'
'400':
description: Invalid request
components:
schemas:
OrderRequest:
type: object
required:
- customerId
- items
- totalAmount
properties:
customerId:
type: string
description: Unique customer identifier
items:
type: array
items:
type: object
properties:
productId:
type: string
quantity:
type: integer
unitPrice:
type: number
totalAmount:
type: number
description: Total order amount in currency units
OrderResult:
type: object
properties:
orderId:
type: string
description: Unique order identifier
customerId:
type: string
status:
type: string
enum: [confirmed, pending, failed]
totalAmount:
type: number
timestamp:
type: string
format: date-time
WireTransferRequest:
type: object
required:
- fromAccount
- toAccount
- amount
- currency
properties:
fromAccount:
type: string
description: Source account number
toAccount:
type: string
description: Destination account number
amount:
type: number
description: Transfer amount
currency:
type: string
description: ISO 4217 currency code
referenceNumber:
type: string
description: Optional transfer reference
WireTransferResult:
type: object
properties:
transferId:
type: string
description: Unique transfer identifier
status:
type: string
enum: [completed, pending, failed]
amount:
type: number
currency:
type: string
executionTime:
type: string
format: date-time
errorMessage:
type: string
description: Error details if transfer failed
Raw
overlay-refactored.yaml
overlay: 1.1.0
info:
title: Payment Service API Enhancement
version: 1.0.0
description: Adds monitoring operations for orders and wire transfers
x-components:
actions:
addMonitoringPathItem:
fields:
description: Adds a monitoring GET operation to the API
target: '$.paths[''%param.pathItemKey%'']'
update:
get:
operationId: '%param.operationId%'
summary: 'Monitor a %param.resourceName%'
description: 'Retrieve the current status and details of a %param.resourceName%'
parameters:
- name: '%param.idParamName%'
in: path
required: true
description: 'The %param.resourceName% identifier to monitor'
schema:
type: string
responses:
'200':
description: '%param.resourceName% details retrieved successfully'
content:
application/json:
schema:
$ref: '#/components/schemas/%param.resultSchemaName%'
'404':
description: '%param.resourceName% not found'
addMonitoringSchema:
fields:
description: Adds a monitoring result schema to components
target: '$.components.schemas'
update:
'%param.schemaName%':
type: object
properties:
'%param.resourcePropertyName%':
$ref: '#/components/schemas/%param.nestedSchemaRef%'
lastUpdated:
type: string
format: date-time
'%param.additionalProperty%':
type: string
actions:
# Add both monitoring paths using a single reusable action with different parameters
- x-$ref: '#/components/actions/addMonitoringPathItem'
x-parameterValues:
pathItemKey: /orders/{orderId}
operationId: monitor_order
resourceName: order
idParamName: orderId
resultSchemaName: OrderMonitorResult
- x-$ref: '#/components/actions/addMonitoringPathItem'
x-parameterValues:
pathItemKey: /transfers/{transferId}
operationId: monitor_wire_transfer
resourceName: wire transfer
idParamName: transferId
resultSchemaName: WireTransferMonitorResult
# Add OrderMonitorResult schema
- x-$ref: '#/components/actions/addMonitoringSchema'
x-parameterValues:
schemaName: OrderMonitorResult
resourcePropertyName: order
nestedSchemaRef: OrderResult
additionalProperty: trackingInfo
# Add WireTransferMonitorResult schema
- x-$ref: '#/components/actions/addMonitoringSchema'
x-parameterValues:
schemaName: WireTransferMonitorResult
resourcePropertyName: transfer
nestedSchemaRef: WireTransferResult
additionalProperty: confirmationNumber
Raw
overlay.yaml
overlay: 1.1.0
info:
title: Payment Service API Enhancement
version: 1.0.0
description: Adds monitoring operations for orders and wire transfers
x-components:
actions:
addMonitoringPathItem:
fields:
description: Adds a monitoring GET operation to the API
update:
get:
operationId: '%param.operationId%'
summary: 'Monitor a %param.resourceName%'
description: 'Retrieve the current status and details of a %param.resourceName%'
parameters:
- name: '%param.idParamName%'
in: path
required: true
description: 'The %param.resourceName% identifier to monitor'
schema:
type: string
responses:
'200':
description: '%param.resourceName% details retrieved successfully'
content:
application/json:
schema:
$ref: '#/components/schemas/%param.resultSchemaName%'
'404':
description: '%param.resourceName% not found'
addMonitoringSchema:
fields:
description: Adds a monitoring result schema to components
update:
'%param.schemaName%':
type: object
properties:
'%param.resourcePropertyName%':
$ref: '#/components/schemas/%param.nestedSchemaRef%'
lastUpdated:
type: string
format: date-time
'%param.additionalProperty%':
type: string
actions:
# Add the /orders/{orderId} monitoring path
- x-$ref: '#/components/actions/addMonitoringPathItem'
target: '$.paths[''/orders/{orderId}'']'
x-parameterValues:
operationId: monitor_order
resourceName: order
idParamName: orderId
resultSchemaName: OrderMonitorResult
# Add the /transfers/{transferId} monitoring path
- x-$ref: '#/components/actions/addMonitoringPathItem'
target: '$.paths[''/transfers/{transferId}'']'
x-parameterValues:
operationId: monitor_wire_transfer
resourceName: wire transfer
idParamName: transferId
resultSchemaName: WireTransferMonitorResult
# Add OrderMonitorResult schema
- x-$ref: '#/components/actions/addMonitoringSchema'
target: '$.components.schemas'
x-parameterValues:
schemaName: OrderMonitorResult
resourcePropertyName: order
nestedSchemaRef: OrderResult
additionalProperty: trackingInfo
# Add WireTransferMonitorResult schema
- x-$ref: '#/components/actions/addMonitoringSchema'
target: '$.components.schemas'
x-parameterValues:
schemaName: WireTransferMonitorResult
resourcePropertyName: transfer
nestedSchemaRef: WireTransferResult
additionalProperty: confirmationNumber
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment