Passer au contenu principal
Les pages d’endpoints et le playground d’API affichent tout ce que décrit votre spécification OpenAPI. Cette page couvre les parties d’une spécification qui modifient la façon dont Mintlify affiche les requêtes et les réponses : schémas composés, champs conditionnels, téléversements de fichiers, exemples et types de contenu de réponse, webhooks et callbacks.

Combiner des schémas

OpenAPI fournit des mots-clés pour combiner des schémas :
  • allOf : combine plusieurs schémas, par exemple pour fusionner des objets ou étendre un schéma de base. Fonctionne comme un opérateur and.
  • anyOf : accepte les données correspondant à l’un des schémas fournis. Fonctionne comme un opérateur or.
  • oneOf : accepte les données correspondant à exactement un des schémas fournis. Fonctionne comme un opérateur exclusive-or.
Mintlify traite 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.

Fusionner des objets avec allOf

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.
object

Proposer des options avec oneOf et anyOf

Lorsque vous utilisez 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 :
object
string
L’adresse postale du domicile
Les champs de type 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.

Exigences conditionnelles

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 :
La page de l’endpoint étiquette ces champs :
  • card_number : obligatoire si method = card
  • account_number : obligatoire sauf si method = card
  • company_name : obligatoire si tax_id est défini
Mintlify résume les conditions qui testent des valeurs précises de propriétés sœurs avec 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.
Un test de propriété dans if réussit aussi lorsque la propriété est absente. Pour obtenir une étiquette précise, rendez la propriété testée obligatoire, dans la liste required de l’objet ou dans la liste required du schéma if. Sinon, le champ affiche la pastille conditionally required.

Téléversements de fichiers

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.
Vous pouvez utiliser des types de média binaires comme 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.

Plusieurs exemples de réponse

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.

Types de contenu de réponse

Le playground affiche les réponses en fonction de l’en-tête 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.
Pour afficher un lecteur audio dans un exemple de réponse, définissez le type de contenu de la réponse sur audio/* et utilisez l’URL d’un fichier audio comme valeur d’exemple :

Réponses en streaming

Si les réponses d’un endpoint déclarent un type de média de streaming, le playground affiche la réponse au fur et à mesure qu’elle arrive au lieu d’attendre la fin de la requête. Les types de média de streaming sont 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

Les webhooks sont des callbacks HTTP que votre API envoie pour notifier des systèmes externes lorsque des événements se produisent. Les documents OpenAPI 3.1 et ultérieurs prennent en charge les webhooks. Ajoutez un champ 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 :
Le nom du webhook doit correspondre exactement à la clé du champ webhooks de votre spécification OpenAPI.

Callbacks

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.