api.playground de votre docs.json.
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.
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.
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.- 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.
security pour une opération. Pour plus d’informations, consultez Authentication dans la documentation OpenAPI.
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.
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.
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.
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
scopesdans lesflowsdu schéma OAuth 2.0. - Dans OpenAPI 3.1, les listes de rôles des exigences
apiKeyethttp, 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.
api.playground.display dans votre docs.json pour contrôler ce qui apparaît sur chaque page d’endpoint :
interactive(par défaut) : le playground complet.simple: un endpoint copiable sans playground.none: aucun playground.auth: le playground complet pour les lecteurs connectés, et rien pour les autres. Consultez Afficher le playground uniquement aux lecteurs connectés.
docs.json
playground dans le frontmatter de la page, ou dans x-mint.metadata pour une page générée.
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.
admin ou developer voient le playground.
Pour les pages générées, définissez les mêmes champs dans x-mint.metadata :
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
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.
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
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.