[ADP-756] OpenAPI: Provide Examples
Guidance
- MUST provide examples for request and response
Example
Here is an example of an OpenAPI document snippet with properly defined examples for requests and responses:
yaml
openapi: 3.0.1
info:
title: Parcel Service API
description: API for managing parcel services
version: 1.0.0
paths:
/parcels:
post:
summary: Create a new parcel
operationId: createParcel
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Parcel'
examples:
createParcel:
summary: Example of a request to create a new parcel
value:
sender: John Doe
receiver: Jane Smith
weight: 2.5
dimensions:
length: 10
width: 15
height: 5
responses:
'201':
description: Parcel created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Parcel'
examples:
parcelCreated:
summary: Example of a successful response
value:
id: 12345
sender: John Doe
receiver: Jane Smith
weight: 2.5
dimensions:
length: 10
width: 15
height: 5
status: created
'400':
description: Bad request
content:
application/json:
examples:
badRequest:
summary: Example of a bad request response
value:
error: "Invalid parcel dimensions"
components:
schemas:
Parcel:
type: object
properties:
sender:
type: string
receiver:
type: string
weight:
type: number
dimensions:
type: object
properties:
length:
type: number
width:
type: number
height:
type: number
status:
type: string