Passer au contenu principal
Le playground d’API envoie de vraies requêtes à votre API depuis vos pages d’endpoints. Pour fonctionner, il a besoin d’une URL de base et, si votre API l’exige, d’une méthode d’authentification. Les deux proviennent de votre spécification OpenAPI. Les paramètres d’affichage et de réseau proviennent de l’objet api.playground de votre docs.json.

Définir l’URL de base

Ajoutez un champ servers à votre spécification OpenAPI avec l’URL de base de votre API. Le playground ajoute le chemin de chaque endpoint, comme /users/{id}, à cette URL.
Si vous listez plusieurs serveurs, les lecteurs en choisissent un dans une liste déroulante. Si vous ne listez aucun serveur, le playground ne peut pas envoyer de requêtes et affiche l’endpoint en mode simple. Si votre API sert certains endpoints depuis une autre URL, remplacez le champ servers pour un chemin ou une opération. Pour en savoir plus sur le champ servers, consultez API server and base path dans la documentation OpenAPI.

Ajouter l’authentification

Définissez la manière dont les lecteurs s’authentifient avec les champs securitySchemes et security de votre spécification OpenAPI. Le playground ajoute un champ de saisie pour chaque schéma afin que les lecteurs puissent saisir leurs identifiants avant d’envoyer une requête.
1

Définissez votre méthode d'authentification.

Ajoutez un champ securitySchemes. Cet exemple définit une authentification bearer.
2

Appliquez l'authentification à vos endpoints.

Ajoutez un champ security pour exiger le schéma.
Les types d’authentification courants incluent :
  • Clés d’API : pour les clés transmises dans un en-tête, une requête ou un cookie.
  • Bearer : pour les jetons JWT ou OAuth.
  • Basic : pour un nom d’utilisateur et un mot de passe.
Si différents endpoints exigent des méthodes d’authentification différentes, remplacez le champ security pour une opération. Pour plus d’informations, consultez Authentication dans la documentation OpenAPI.

Décrire le champ d’autorisation

Le playground génère une description pour le champ d’autorisation en fonction du type de schéma de sécurité. Pour la remplacer par votre propre texte, par exemple pour indiquer où les lecteurs trouvent leur clé, ajoutez une description au schéma de sécurité. La description prend en charge Markdown et s’applique à chaque endpoint qui utilise le schéma.

Préremplir les identifiants

Ajoutez l’extension x-default à un schéma de sécurité pour préremplir son champ dans le playground, par exemple avec un espace réservé ou un identifiant de test. x-default fonctionne sur les schémas apiKey et http bearer.
Toute personne pouvant ouvrir vos pages d’endpoints peut voir une valeur x-default. N’utilisez jamais un identifiant de production.

Afficher les scopes requis

Si le champ security d’une opération liste des scopes, la page de l’endpoint les affiche dans une section Scopes après la section d’autorisation. Le playground les liste aussi sous le champ de l’option d’autorisation sélectionnée.
La section Scopes liste les scopes de chaque option du champ security, afin que les lecteurs les voient quelle que soit l’option d’autorisation choisie. Dans cet exemple, users:read apparaît même si apiToken est la première option.
  • Les descriptions des scopes proviennent de la table scopes dans les flows du schéma OAuth 2.0.
  • Dans OpenAPI 3.1, les listes de rôles des exigences apiKey et http, comme { "apiKey": ["admin"] }, apparaissent dans la même section.
  • Si plusieurs schémas exigent des scopes, une étiquette à côté de chaque scope indique le nom de son schéma.

Choisir un mode d’affichage

Définissez api.playground.display dans votre docs.json pour contrôler ce qui apparaît sur chaque page d’endpoint :
docs.json
Pour changer le mode d’un endpoint, définissez playground dans le frontmatter de la page, ou dans x-mint.metadata pour une page générée.

Afficher le playground uniquement aux lecteurs connectés

Utilisez le mode d’affichage auth pour garder votre référence d’API publique tout en ne permettant qu’aux lecteurs connectés d’envoyer des requêtes. Le mode auth nécessite une authentification sur votre site. Pour limiter le playground à des groupes d’utilisateurs précis, ajoutez groups au frontmatter de la page. Si la page n’a pas de groups, tous les lecteurs connectés voient le playground.
Dans cet exemple, tout le monde peut lire la page, mais seuls les lecteurs connectés des groupes admin ou developer voient le playground. Pour les pages générées, définissez les mêmes champs dans x-mint.metadata :

Envoyer les requêtes via le proxy

Par défaut, le playground envoie les requêtes via le proxy de Mintlify, de sorte que votre API n’a pas besoin d’accepter les requêtes cross-origin provenant de votre domaine de documentation. Définissez api.playground.proxy sur false pour envoyer les requêtes directement depuis le navigateur du lecteur vers votre API. Faites-le si votre API exige des en-têtes que le proxy ne peut pas transmettre, ou si les requêtes doivent provenir du navigateur du lecteur, par exemple pour une authentification basée sur les cookies. Votre API doit alors autoriser les requêtes cross-origin depuis votre domaine de documentation avec CORS. Pour envoyer des cookies, des en-têtes d’autorisation et des certificats client TLS avec les requêtes directes, définissez aussi credentials sur true.
docs.json
Si vous servez votre documentation via un reverse proxy sur un domaine personnalisé, le reverse proxy doit autoriser les requêtes POST vers le chemin /_mintlify/api/request. Lorsque le proxy de Mintlify est activé, le playground envoie chaque requête sous forme de POST vers ce chemin. Si votre reverse proxy ne peut pas autoriser les requêtes POST, définissez proxy sur false.

Préremplir des valeurs d’exemple

Pour remplir les champs de la requête avec les valeurs d’exemple de votre spécification OpenAPI, définissez api.examples.prefill sur true dans votre docs.json.
docs.json
Pour préremplir un champ avec une valeur différente de son default dans le schéma, ajoutez x-default à la propriété. x-default sur une propriété ne prend effet que lorsque prefill vaut true. x-default sur un schéma de sécurité prend toujours effet. Pour la liste complète des paramètres du playground, consultez Paramètres d’API.