Copy the block below into an openapi.yaml and replace the <placeholders>.
openapi: 3.1.0
info:
title: Orders API
version: 1.0.0
description: Read and write the orders belonging to the authenticated customer.
servers:
- url: https://api.example.com
tags:
- name: orders
description: Customer orders
paths:
/orders:
get:
operationId: listOrders
tags: [orders]
summary: List the customer's orders
parameters:
- name: page
in: query
required: false
schema: { type: integer, minimum: 1, default: 1 }
- name: page_size
in: query
required: false
schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
- name: status
in: query
required: false
schema: { type: string, enum: [new, paid, shipped, cancelled] }
responses:
'200':
description: A page of orders
content:
application/json:
schema: { $ref: '#/components/schemas/OrderList' }
'401':
$ref: '#/components/responses/Unauthenticated'
post:
operationId: createOrder
tags: [orders]
summary: Create an order
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CreateOrder' }
responses:
'201':
description: The created order
headers:
Location:
description: The URL of the created order
schema: { type: string, format: uri }
content:
application/json:
schema: { $ref: '#/components/schemas/Order' }
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthenticated'
/orders/{orderId}:
parameters:
- name: orderId
in: path
required: true
schema: { type: string, pattern: '^A-[0-9]+$' }
get:
operationId: getOrder
tags: [orders]
summary: Fetch a single order
responses:
'200':
description: The order
content:
application/json:
schema: { $ref: '#/components/schemas/Order' }
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/AccessDenied'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateOrder
tags: [orders]
summary: Update an order
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/UpdateOrder' }
responses:
'200':
description: The updated order
content:
application/json:
schema: { $ref: '#/components/schemas/Order' }
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/AccessDenied'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/Unprocessable'
components:
schemas:
CreateOrder:
type: object
additionalProperties: false
required: [items]
properties:
items:
type: array
minItems: 1
maxItems: 100
items:
type: object
additionalProperties: false
required: [sku, quantity]
properties:
sku: { type: string, pattern: '^[A-Z]{3}-[0-9]{4}$' }
quantity: { type: integer, minimum: 1, maximum: 999 }
UpdateOrder:
type: object
additionalProperties: false
properties:
status:
type: string
enum: [new, paid, shipped, cancelled]
Order:
type: object
additionalProperties: false
required: [id, status, total, currency, createdAt]
properties:
id: { type: string, pattern: '^A-[0-9]+$' }
status: { type: string, enum: [new, paid, shipped, cancelled] }
total: { type: number, format: decimal, minimum: 0 }
currency: { type: string, enum: [EUR, USD, GBP] }
createdAt: { type: string, format: date-time }
items:
type: array
items:
type: object
additionalProperties: false
required: [sku, quantity]
properties:
sku: { type: string, pattern: '^[A-Z]{3}-[0-9]{4}$' }
quantity: { type: integer, minimum: 1 }
OrderList:
type: object
additionalProperties: false
required: [items, total, page, pageSize]
properties:
items:
type: array
items: { $ref: '#/components/schemas/Order' }
total: { type: integer, minimum: 0 }
page: { type: integer, minimum: 1 }
pageSize: { type: integer, minimum: 1, maximum: 100 }
Error:
type: object
additionalProperties: false
required: [code, message]
properties:
code: { type: string }
message: { type: string }
responses:
BadRequest:
description: The request body is malformed
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
example: { code: "MALFORMED_BODY", message: "Request body is not valid JSON." }
Unauthenticated:
description: No valid credentials were supplied
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
example: { code: "AUTHENTICATION_REQUIRED", message: "A valid access token is required." }
AccessDenied:
description: The order does not belong to the authenticated customer
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
example: { code: "ORDER_ACCESS_DENIED", message: "This order does not belong to you." }
NotFound:
description: No such order
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
example: { code: "ORDER_NOT_FOUND", message: "No order exists with that identifier." }
Unprocessable:
description: The request is well-formed but cannot be processed
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
example: { code: "ORDER_STATE_INVALID", message: "This order can no longer be changed." }
Why it is shaped this way
operationId on every operation. It is the join key between the contract and the behaviour. Without it, a scenario cannot reference an operation, and the cross-format consistency check has nothing to check.
additionalProperties: false on every schema. Without it, a service that starts sending a new field passes validation while a strict consumer breaks. Turn it on unless you genuinely want an open schema.
Every error response has a schema and an example. The example is validated against the schema during the build, which catches the copies that were never updated. And the literal error codes in the examples are what the Gherkin scenarios assert against.
The 403 and the 404 are separate responses. They mean different things and leak different information. Deciding to conflate them is a legitimate choice — but it should be written down as one, not arrived at by accident.
Constraints are structural, not prose. minimum, maximum, pattern, enum, minItems are all executable checks. A comment saying "must be a positive amount" is not.
422 is distinguished from 400. 400 is a malformed request; 422 is a well-formed request that cannot be processed. Splitting them means a client can tell "fix your JSON" from "you cannot do that right now".
Parameters are constrained at the boundary. page_size has maximum: 100, and the behaviour template has a scenario asserting that a larger value is refused with PAGE_SIZE_TOO_LARGE. The constraint and the behaviour are specified in their respective halves, and the consistency check verifies they agree.
Pair it with a behaviour file
This contract is shapes. The behaviour — when an order may be changed, what cancelling one does to a payment, which transitions are legal — belongs in a Gherkin feature file. See the REST API behaviour template.
Related
- OpenAPI documents — what the contract can and cannot prove
- OpenAPI contract testing — the checks this template makes executable
- Cross-format consistency — how the two halves are checked against each other