Les corps des requêtes sont typiquement utilisés avec les opérations de «création» et de «mise à jour» (POST, PUT, PATCH). Par exemple, lorsqu’une ressource est créée avec POST ou PUT, le corps de la requête contient généralement la représentation de la ressource pour être créée. OpenAPI 3.0 fournis le mot clé requestBody pour décrire le corps de la requête.
Différence par rapport à OpenAPI 2.0
Si vous utilisiez OpenAPI 2.0 par le passé, pour vous aider, voici un résumé des changements intervenus avec OpenAPI 3.0:
- Les paramètres
bodyetformsont remplacés parrequestBody; - Les opérations supportent désormais à la fois les données formulaires et d’autres formats de donnée tel que JSON;
- Le tableau
consumesest remplacé avec le dictionnairerequestBody.contentreliant le type de format à leurs schémas; - Les schémas peuvent varier selon le format;
anyOfetoneOfpeuvent être utilisés pour spécifier un schéma alternatif;- Les données issues de formulaire {Form data} peuvent maintenant contenir des objets, et vous pouvez spécifier la méthode de sérialisation pour les objets et les tableaux;
- Les méthodes GET, DELETE et HEAD ne sont plus autorisées à avoir des corps de requêtes car cela n’est pas défini par RFC 7231.
requestBody, contenu et format de données
Contrairement à OpenAPI 2.0 où le corps de la requête est défini en utilisant les paramètres body et formData, OpenAPI 3.0 utilise le mot clé requestBody pour distinguer la charge utile des paramètres (comme query string). Le paramètre requestBody est plus flexible en vous permettant d’employer plusieurs formats de donnée comme XML, JSON, données de formulaire, texte brut ou autre; et d’utiliser différents schémas selon le format. requestBody se constitue de l’objet content, une description optionnelle en Markdown et un drapeau required (false par défaut). Le paramètre content liste les formats utilisés par les opérations (comme application/json) et spécifie le schema pour chacun d’eux. Les corps de requête sont optionnels par défaut; pour les marquer comme obligatoire utilisez: required: true.
paths:
/pets:
post:
summary: Add a new pet
requestBody:
description: Optional description in *Markdown*
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PetForm'
text/plain:
schema:
type: string
responses:
'201':
description: Created
L’objet content autorise les formats jokers. Par exemple, image/* indique tous les formats d’images; */* représente touts les format et est fonctionnellement équivalent à application/octet-stream. Un format spécifique est meilleur que les formats jokers lors de l’interprétation de la spécification, par exemple image/png > image/* > */*.
paths:
/avatar:
put:
summary: Upload an avatar
requestBody:
content:
image/*: # Can be image/png, image/svg, image/gif, etc.
schema:
type: string
format: binary
anyOf, oneOf
OpenAPI 3.0 supporte anyOf et oneOf, donc vous pouvez spécifier des schémas alternatifs pour le corps de la requête:
requestBody:
description: A JSON object containing pet information
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Hamster'
Téléversement de fichier
Pour apprendre comment spécifier l’envoie de fichier, voir File Upload et Multipart Requests.
Exemple de corps de requête
Le corps de la requête peut avoir un example ou plusieurs examples.example et examples sont des propriétés de l’objet requestBody.content.<media-type>. Si fournis, ces exemples surchargent les exemples fournis par le schéma. Cela peut être utile, par exemple dans le cas où la requête et la réponse ont le même schéma mais que l’on souhaite avoir exemple différent pour chacun. example permet un exemple en une ligne.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
example:
name: Fluffy
petType: dog
L’utilisation de examples (au pluriel) est plus flexibles, vous pouvez avoir un exemple sur une ligne, une référence avec $ref, ou un lien vers une URL externe contenant un exemple de charge utile. Chaque exemple peut éventuellement avoir summary et description pour les documenter.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
examples:
dog: # <--- example name
summary: An example of a dog
value:
# vv Actual payload goes here vv
name: Fluffy
petType: dog
cat: # <--- example name
summary: An example of a cat
externalValue: http://api.example.com/examples/cat.json
# cat.json contains {"name": "Tiger", "petType": "cat"}
hamster: # <--- example name
$ref: '#/components/examples/hamster'
components:
examples:
hamster: # <--- example name
summary: An example of a hamster
value:
# vv Actual payload goes here vv
name: Ginger
petType: hamster
Voir Adding Examples pour plus d’information.
Corps réutilisable
Vous pouvez ajouter la définition du corps de la requête dans la section générale components.requestBodies et s’y référer ailleurs avec $ref. Cela est pratique quand plusieurs opérations utilisent le même corps. Cela permet de facilement réutiliser la même définition.
paths:
/pets:
post:
summary: Add a new pet
requestBody:
$ref: '#/components/requestBodies/PetBody'
/pets/{petId}
put:
summary: Update a pet
parameters: [ ... ]
requestBody:
$ref: '#/components/requestBodies/PetBody'
components:
requestBodies:
PetBody:
description: A JSON object containing pet information
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
Donnée de formulaire
Le terme « donnée de formulaire» (form data dans la version anglaise) est utilisé pour désigner le format application/x-www-form-urlencoded et multipart/form-data, qui sont communément utilisés pour soumettre les formulaires HTML.
application/x-www-form-urlencodedest utilisé pour envoyer de simple texte ASCII sous forme de paireclé=valeur. Le format de la charge utile est similaire à query parameters.multipart/form-datapermet de soumettre des données binaires ainsi que plusieurs formats en un unique message (par exemple une image et du JSON). Chaque champ du formulaire a sa propre section dans la charge utile avec des entêtes HTTP internes. Les requêtesmultipartsont couramment utilisées pour les file uploads.
Pour illustré cela, considérons le formulaire HTML suivant utilisant la méthode POST:
<form action="http://example.com/survey" method="post">
<input type="text" name="name" />
<input type="number" name="fav_number" />
<input type="submit"/>
</form>
Ces données sont envoyées avec la méthode POST au point de terminaison:
POST /survey HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 28
name=Amy+Smith&fav_number=42
Dans OpenAPI 3.0, les données de formulaire sont modélisées en utilisant un schéma type: object dans lequel les propriétés de l’objet représentent les champs du formulaire.
paths:
/survey:
post:
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name: # <!--- form field name
type: string
fav_number: # <!--- form field name
type: integer
required:
- name
- email
Un champ peut contenir des valeurs primitives, des tableaux et des objets. Par défaut, les tableaux sont sérialisés comme array_name=value1&array_name=value2 et les objets comme prop1=value1&prop2=value2, mais vous pouvez utiliser d’autres stratégies de sérialisation comme défini par la Spécification OpenAPI 3.0. La stratégie de sérialisation est spécifique à la section encoding comme ci-dessous:
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
color:
type: array
items:
type: string
encoding:
color: # color=red,green,blue
style: form
explode: false
Par défaut, les caractères réservés :/?#[]@!$&'()*+,;= dans les champs de formulaire dans un corps application/x-www-form-urlencoded sont encodés avec le pourcentage quand ils sont envoyés. Pour permettre à ces caractères d’être envoyés en l’état, utilisez le mot-clé allowReserved comme ci-dessous:
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
foo:
type: string
bar:
type: string
baz:
type: string
encoding:
# Don't percent-encode reserved characters in the values of "bar" and "baz" fields
bar:
allowReserved: true
baz:
allowReserved: true
Les paires arbitraires clé=valeur peuvent être modelées en utilisant le schéma libre:
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
additionalProperties: true # this line is optional
Sérialisation complexe de donnée de formulaire
Les règles de sérialisation fournis par les mot-clés style et explode ont des comportements seulement définis pour les tableaux de primitives et les objets avec des propriétés primitives. Dans des cas plus complexe, comme des tableaux emboîtés ou des données en JSON dans un formulaire, vous avez besoin d’utiliser le mot-clé contentType pour spécifier le format pour encoder les valeurs d’un champ complexe. Considéré Slack incoming webhooks comme un exemple. Un message peut-être envoyé directement en JSON, ou alors, les données JSON peuvent être à l’intérieur d’un champ nommé payload comme ci-dessous (avant que l’encodage d’URL soit appliqué):
payload={"text":"Swagger is awesome"}
Cela peut être décrit comme:
openapi: 3.0.0
info:
version: 1.0.0
title: Slack Incoming Webhook
externalDocs:
url: https://api.slack.com/incoming-webhooks
servers:
- url: https://hooks.slack.com
paths:
/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX:
post:
summary: Post a message to Slack
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
application/x-www-form-urlencoded:
schema:
type: object
properties:
payload: # <--- form field that contains the JSON message
$ref: '#/components/schemas/Message'
encoding:
payload:
contentType: application/json
responses:
'200':
description: OK
components:
schemas:
Message:
title: A Slack message
type: object
properties:
text:
type: string
description: Message text
required:
- text