> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-f05786c0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Playground

> Laissez les développeurs tester les endpoints d'API dans votre documentation avec un playground interactif qui envoie de vraies requêtes et réponses.

Le playground API est un environnement interactif qui permet aux utilisateurs de tester et d’explorer vos endpoints d’API. Les développeurs peuvent composer des requêtes API, les envoyer et consulter les réponses sans quitter votre documentation.

Voir [Déclencher une mise à jour](/fr/api/update/trigger) pour un exemple du playground API en action.

<Frame>
  <img src="https://mintcdn.com/mintlify-mintlify-f05786c0/pppDfyZJ_diOBpZf/images/playground/API-playground-light.png?fit=max&auto=format&n=pppDfyZJ_diOBpZf&q=85&s=580e844559e1ada2d6f3fdd830927b76" alt="Playground API pour l’endpoint « Déclencher une mise à jour »." className="block dark:hidden" width="2534" height="1022" data-path="images/playground/API-playground-light.png" />

  <img src="https://mintcdn.com/mintlify-mintlify-f05786c0/pppDfyZJ_diOBpZf/images/playground/API-playground-dark.png?fit=max&auto=format&n=pppDfyZJ_diOBpZf&q=85&s=c4b357c87444df2538032e152dc62f01" alt="Playground API pour l’endpoint « Déclencher une mise à jour »." className="hidden dark:block" width="2534" height="1022" data-path="images/playground/API-playground-dark.png" />
</Frame>

Le playground génère des pages interactives pour vos endpoints à partir de votre spécification OpenAPI ou de votre schéma AsyncAPI. Si vous modifiez votre API, il met automatiquement à jour les pages concernées.

Nous recommandons de générer votre playground API à partir d’une spécification OpenAPI. Cependant, vous pouvez créer manuellement des pages de référence de l’API après avoir défini une URL de base et une méthode d’authentification dans votre `docs.json`.

<div id="get-started">
  ## Premiers pas
</div>

<Steps>
  <Step title="Ajoutez votre fichier de spécification OpenAPI.">
    <Tip>
      Validez votre fichier de spécification OpenAPI avec le [Swagger Editor](https://editor.swagger.io/) ou la commande [Mint CLI](https://www.npmjs.com/package/mint) `mint validate`.
    </Tip>

    ```bash {3} theme={null}
    /your-project
      |- docs.json
      |- openapi.json
    ```
  </Step>

  <Step title="Générez les pages des endpoints.">
    Mettez à jour votre `docs.json` pour référencer votre spécification OpenAPI.

    **Pour générer automatiquement des pages pour tous les endpoints de votre spécification OpenAPI**, ajoutez une propriété `openapi` à n’importe quel élément de navigation.

    Cet exemple génère une page pour chaque endpoint défini dans `openapi.json` et organise les pages dans le groupe « Référence API ».

    ```json Generate all endpoint pages theme={null}
    "navigation": {
      "groups": [
        {
          "group": "API reference",
          "openapi": "openapi.json"
        }
      ]
    }
    ```

    **Pour ne générer des pages que pour certains endpoints**, énumérez-les dans la propriété `pages` de l’élément de navigation.

    Cet exemple génère des pages uniquement pour les endpoints `GET /users` et `POST /users`. Pour générer d’autres pages d’endpoints, ajoutez-les au tableau `pages`.

    ```json Generate specific endpoint pages theme={null}
    "navigation": {
      "groups": [
          {
            "group": "API reference",
            "openapi": "openapi.json",
            "pages": [
              "GET /users",
              "POST /users"
            ]
          }
      ]
    }
    ```
  </Step>
</Steps>

<div id="customize-your-playground">
  ## Personnaliser votre bac à sable
</div>

Personnalisez votre bac à sable d’API en définissant les propriétés suivantes dans votre `docs.json`.

<ResponseField name="playground" type="object">
  Configurations du bac à sable d’API.

  <Expandable title="playground" defaultOpen="True">
    <ResponseField name="display" type="&#x22;interactive&#x22; | &#x22;simple&#x22; | &#x22;none&#x22; | &#x22;auth&#x22;">
      Le mode d’affichage du bac à sable d’API.

      * `"interactive"`: Affiche le bac à sable interactif.
      * `"simple"`: Affiche un endpoint copiable sans bac à sable.
      * `"none"`: N’affiche rien.
      * `"auth"`: Affiche le bac à sable interactif uniquement aux utilisateurs authentifiés. Les utilisateurs non authentifiés ou qui ne font pas partie des groupes requis ne voient aucun bac à sable.

      Valeur par défaut : `interactive`.
    </ResponseField>

    <ResponseField name="proxy" type="boolean" defaultOpen="True">
      Indique s'il faut faire passer les requêtes API via le serveur proxy de Mintlify. Valeur par défaut : `true`.

      Lorsque `true`, les requêtes du playground sont acheminées via les serveurs de Mintlify. Lorsque `false`, le playground envoie les requêtes directement depuis le navigateur vers votre API. Définissez sur `false` lorsque votre API accepte les requêtes directes du navigateur et que vous n'avez pas besoin que Mintlify serve de proxy pour le trafic. Par exemple, lorsque votre API nécessite des en-têtes spécifiques qui ne peuvent pas être transmis via le proxy ou lorsque vous avez besoin que la requête provienne directement du navigateur de l'utilisateur à des fins d'authentification.
    </ResponseField>

    <ResponseField name="credentials" type="boolean">
      Indique s'il faut inclure les cookies, les en-têtes d'autorisation et les certificats client TLS pour les requêtes cross-origin lorsque `proxy` est `false`. Valeur par défaut : `false`.

      Lorsque `true` et que `proxy` est `false`, le playground envoie les requêtes avec les identifiants gérés par le navigateur inclus. Par exemple, lorsque votre API utilise l'authentification par cookies ou des jetons de session HTTP.

      Cette option n'a aucun effet lorsque `proxy` est `true`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="url" type="&#x22;full&#x22;">
  Le mode d’affichage des URL de base dans les en-têtes des endpoints. Lorsqu’il est défini sur `full`, l’URL de base complète s’affiche sur chaque page d’endpoint. Par défaut, seul le chemin relatif de l’endpoint s’affiche.
</ResponseField>

<ResponseField name="examples" type="object">
  Configurations pour les exemples d’API générés automatiquement.

  <Expandable title="examples" defaultOpen="True">
    <ResponseField name="languages" type="array of string">
      Langues d’exemples pour les extraits d’API générés automatiquement.

      Les langues s’affichent dans l’ordre indiqué.

      <Accordion title="Toutes les langues prises en charge">
        | Nom affiché | Clé          | Alias                     |
        | ----------- | ------------ | ------------------------- |
        | cURL        | `bash`       | `curl`, `sh`, `shell`     |
        | Python      | `python`     | `py`                      |
        | JavaScript  | `javascript` | `js`                      |
        | Node.js     | `node`       | `nodejs`, `node.js`       |
        | PHP         | `php`        |                           |
        | Go          | `go`         | `golang`                  |
        | Java        | `java`       |                           |
        | Ruby        | `ruby`       | `rb`                      |
        | PowerShell  | `powershell` |                           |
        | Swift       | `swift`      |                           |
        | C#          | `csharp`     | `c#`                      |
        | .NET        | `dotnet`     | `.net`, `.NET`, `dot-net` |
        | TypeScript  | `typescript` | `ts`                      |
        | C           | `c`          |                           |
        | C++         | `c++`        | `cpp`                     |
        | Kotlin      | `kotlin`     | `kt`                      |
        | Rust        | `rust`       | `rs`                      |
        | Dart        | `dart`       | `flutter`                 |
      </Accordion>
    </ResponseField>

    <ResponseField name="defaults" type="&#x22;required&#x22; | &#x22;all&#x22;">
      Indique s’il faut afficher les paramètres optionnels dans les exemples d’API. Valeur par défaut : `all`.
    </ResponseField>

    <ResponseField name="prefill" type="boolean">
      Indique s’il faut préremplir le bac à sable d’API avec des données tirées des exemples de schéma. Lorsque cette option est activée, le bac à sable remplit automatiquement les champs de requête avec des valeurs d’exemple provenant de votre spécification OpenAPI. Valeur par défaut : `false`.
    </ResponseField>

    <ResponseField name="autogenerate" type="boolean">
      Indique s’il faut générer des exemples de code pour les endpoints à partir des spécifications d’API. Valeur par défaut : `true`. Lorsque cette option est définie sur `false`, seuls les exemples de code écrits manuellement (depuis `x-codeSamples` dans les spécifications OpenAPI ou les composants `<RequestExample>` dans le MDX) apparaissent dans le bac à sable d’API.
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="example-configuration">
  ### Exemple de configuration
</div>

Cet exemple configure l’aire de test de l’API pour être interactive, avec des extraits de code pour cURL, Python et JavaScript. Il n’affiche que les paramètres requis dans les extraits de code, et l’aire de test préremplit le corps de la requête avec des valeurs d’exemple.

```json theme={null}
{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required",
     "prefill": true
   }
 }
}
```

<div id="auth-based-playground-display">
  ### Affichage du playground basé sur l’authentification
</div>

Utilisez le mode d’affichage `auth` pour afficher le playground interactif uniquement aux utilisateurs authentifiés. C’est utile lorsque vous voulez rendre la documentation de votre API publique tout en restreignant l’accès au playground aux utilisateurs connectés.

Lorsque `display` est défini sur `auth` :

* Les utilisateurs authentifiés voient le playground interactif.
* Les utilisateurs non authentifiés ne voient aucun playground (équivalent à `none`).

Vous pouvez également combiner `auth` avec la propriété `groups` dans le frontmatter de la page pour restreindre l’accès au playground à des groupes d’utilisateurs spécifiques.

```mdx Page with group-restricted playground theme={null}
---
title: "Créer un utilisateur"
openapi: POST /users
playground: auth
groups: ["admin", "developer"]
public: true
---
```

Dans cet exemple :

* La page est publique (tout le monde peut consulter la documentation).
* Seuls les utilisateurs authentifiés appartenant aux groupes `admin` ou `developer` voient l'espace de test interactif.
* Les utilisateurs qui ne sont pas dans ces groupes ne voient aucun espace de test.

Si la page ne comporte pas de propriété `groups`, tous les utilisateurs authentifiés voient l'espace de test interactif.

<Note>
  Le mode d'affichage `auth` nécessite que votre documentation ait l'[authentification](/fr/deploy/authentication-setup) configurée.
</Note>

<div id="custom-endpoint-pages">
  ### Pages d’endpoint personnalisées
</div>

Lorsque vous avez besoin d’un contrôle plus fin sur votre documentation d’API, utilisez l’extension `x-mint` dans votre spécification OpenAPI ou créez des pages MDX individuelles pour vos endpoints.

Les deux options vous permettent de :

* Personnaliser la metadata de la page
* Ajouter du contenu supplémentaire, comme des exemples
* Contrôler le comportement du playground pour chaque page

Nous recommandons l’extension `x-mint` afin que toute votre documentation d’API soit automatiquement générée à partir de votre spécification OpenAPI et maintenue dans un seul fichier.

Nous recommandons les pages MDX individuelles pour les petites API ou lorsque vous souhaitez expérimenter des modifications page par page.

<div id="response-rendering">
  ## Rendu des réponses
</div>

Le playground rend automatiquement les réponses en fonction de l'en-tête `Content-Type` renvoyé par votre API.

* **Images** : Rendues en ligne (`image/*`).
* **Audio** : Rendu avec un lecteur audio intégré (`audio/*`).
* **Vidéo** : Rendue avec un lecteur vidéo intégré (`video/*`). Toute réponse avec un type de contenu `video/*`, tel que `video/mp4` ou `video/webm`, s'affiche sous forme de vidéo lisible directement dans le playground.
* **Toutes les autres réponses** : Affichées dans un bloc de code.

<div id="parameter-anchor-links">
  ## Liens d'ancrage des paramètres
</div>

Chaque paramètre dans le playground API dispose d'un lien d'ancrage cliquable. Survolez le nom d'un paramètre pour révéler l'icône de lien, puis cliquez pour copier une URL directe vers ce paramètre.

Utilisez les liens d'ancrage des paramètres pour :

* Partager des liens vers des paramètres spécifiques dans des conversations de support ou de la documentation
* Naviguer directement vers un paramètre depuis une autre page ou une ressource externe
* Ajouter aux favoris les paramètres fréquemment consultés

Le format de l'URL est `votre-url-docs/chemin-endpoint#nom-du-parametre`. Pour les paramètres imbriqués, l'ancrage inclut le chemin du parent.

<div id="further-reading">
  ## Pour aller plus loin
</div>

* [Configuration d’OpenAPI](/fr/api-playground/openapi-setup) pour en savoir plus sur la création de votre document OpenAPI.
* [Extension x-mint](/fr/api-playground/openapi-setup#customize-your-endpoint-pages) pour en savoir plus sur la personnalisation de vos pages de points de terminaison.
* [Configuration de MDX](/fr/api-playground/mdx-setup) pour en savoir plus sur la création manuelle de pages de référence API individuelles.
* [Configuration d’AsyncAPI](/fr/api-playground/asyncapi-setup) pour en savoir plus sur la création de votre schéma AsyncAPI afin de générer des pages de référence WebSocket.