allOf: combine plusieurs schémas, par exemple pour fusionner des objets ou étendre un schéma de base. Fonctionne comme un opérateurand.anyOf: accepte les données correspondant à l’un des schémas fournis. Fonctionne comme un opérateuror.oneOf: accepte les données correspondant à exactement un des schémas fournis. Fonctionne comme un opérateurexclusive-or.
oneOf et anyOf de manière identique et ne prend pas en charge le mot-clé not. Pour les spécifications détaillées de ces mots-clés, consultez oneOf, anyOf, allOf, not dans la documentation OpenAPI.
Lorsque vous combinez deux schémas d’objet avec allOf, Mintlify fusionne les propriétés des deux en un seul objet. C’est utile avec les composants réutilisables d’OpenAPI.
oneOf ou anyOf, les options s’affichent dans un conteneur à onglets. Indiquez un champ title dans chaque sous-schéma pour nommer les onglets. Par exemple, voici comment afficher deux types d’adresses de livraison :
any ou undefined s’affichent de la même manière que les schémas oneOf, avec un sélecteur qui permet aux utilisateurs de choisir une forme concrète avant d’envoyer une requête.
Dans OpenAPI 3.1, vous pouvez rendre une propriété obligatoire uniquement dans certains cas avec les mots-clés if, then, else, dependentRequired et dependentSchemas. Mintlify lit ces mots-clés et étiquette chaque champ concerné sur la page de l’endpoint avec une pastille required suivie de sa condition.
Par exemple, ce schéma exige un numéro de carte pour les paiements par carte, un numéro de compte pour tous les autres moyens de paiement, et un nom d’entreprise lorsque la requête inclut un identifiant fiscal :
card_number: obligatoire simethod=cardaccount_number: obligatoire sauf simethod=cardcompany_name: obligatoire sitax_idest défini
const ou enum, ou leur présence avec required. Si une condition est trop complexe pour être résumée, le champ affiche à la place une pastille conditionally required.
Pour les spécifications OpenAPI 3.1 et 3.2, définissez un téléversement de fichier comme un schéma de type string avec un contentMediaType binaire. Le playground d’API affiche le champ comme un sélecteur de fichier et l’envoie dans une requête multipart/form-data.
application/octet-stream, des images, de l’audio, de la vidéo, des PDF et des archives. Le playground ne traite pas les types de média structurés comme application/json comme des téléversements de fichiers.
Utilisez contentEncoding pour décrire l’encodage du contenu du fichier. Pour les fichiers encodés en base64, définissez contentEncoding sur base64 ou base64url, et le playground traite le champ comme un fichier base64. Pour toute autre valeur ou en l’absence de valeur, le playground utilise la gestion des fichiers binaires. Une valeur contentEncoding sans contentMediaType binaire reste un champ texte.
Les anciennes valeurs format: "binary" et format: "base64" restent prises en charge.
Si votre API renvoie des réponses différentes selon les paramètres d’entrée, le contexte utilisateur ou d’autres conditions de la requête, documentez chacune d’elles avec la propriété examples de la réponse.
Content-Type renvoyé par votre API :
- Images (
image/*) : affichées en ligne. - Audio (
audio/*) : affiché avec un lecteur audio. - Vidéo (
video/*) : affichée avec un lecteur vidéo. - Toutes les autres réponses : affichées dans un bloc de code.
audio/* et utilisez l’URL d’un fichier audio comme valeur d’exemple :
text/event-stream, application/jsonl, application/x-ndjson, application/json-seq et multipart/mixed. Les requêtes avec un corps multipart/form-data ne sont pas diffusées en streaming.
Pendant la diffusion de la réponse, le panneau de réponse affiche Streaming… et le bouton d’envoi devient Stop. Cliquez sur Stop pour mettre fin à la requête. Le playground conserve les données reçues et affiche Stream stopped.
Le playground affiche un corps diffusé en texte brut, sans mise en forme JSON. Un stream peut aussi se terminer plus tôt :
- Le playground arrête la lecture après 10 Mo et affiche Stream truncated at 10 MB.
- Si la connexion se ferme avant la fin du stream, le playground affiche Stream interrupted.
- Lorsque le proxy du playground est activé, votre API doit envoyer les en-têtes de réponse dans un délai de 30 secondes, et le proxy met fin au stream après cinq minutes.
webhooks à votre document OpenAPI à côté du champ paths. Pour en savoir plus sur la définition des webhooks, consultez Webhooks dans la spécification OpenAPI.
Pour créer une page MDX pour un webhook, utilisez webhook au lieu d’une méthode HTTP dans le frontmatter openapi :
webhooks de votre spécification OpenAPI.
Les callbacks décrivent les requêtes hors bande que votre API envoie à une URL fournie par l’appelant, comme des notifications d’événements liées à une opération précise. Lorsqu’une opération définit des callbacks, la page de l’endpoint les affiche dans une section repliable entre les sections du corps de la requête et de la réponse. Chaque callback affiche sa méthode HTTP et son expression, et utilise la même mise en page de corps et de réponse que l’opération parente.
Pour en savoir plus sur la définition des callbacks, consultez Callback object dans la spécification OpenAPI.