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

# Bac à sable

> Permettez aux utilisateurs d’interagir avec votre API

<div id="overview">
  ## Aperçu
</div>

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

<Frame>
  <img src="https://mintcdn.com/omer-914cc1c6/zyJsbuZtXQKHf9Ui/images/playground/API-playground-light.png?fit=max&auto=format&n=zyJsbuZtXQKHf9Ui&q=85&s=cbd122bacf76749c62b9515b60d55dcd" alt="Bac à sable d’API pour le point de terminaison déclenchant une mise à jour." className="block dark:hidden" width="2534" height="1022" data-path="images/playground/API-playground-light.png" />

  <img src="https://mintcdn.com/omer-914cc1c6/zyJsbuZtXQKHf9Ui/images/playground/API-playground-dark.png?fit=max&auto=format&n=zyJsbuZtXQKHf9Ui&q=85&s=b119dc4c0ce2427d76589461085e3a5d" alt="Bac à sable d’API pour le point de terminaison déclenchant une mise à jour." className="hidden dark:block" width="2534" height="1022" data-path="images/playground/API-playground-dark.png" />
</Frame>

Le bac à sable est généré automatiquement à partir de votre spécification OpenAPI ou de votre schéma AsyncAPI, de sorte que toute mise à jour de votre API est automatiquement répercutée dans le bac à sable. Vous pouvez également 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`.

Nous recommandons de générer votre bac à sable d’API à partir d’une spécification OpenAPI. Consultez [Configuration OpenAPI](/fr/api-playground/openapi-setup) pour plus d’informations sur la création de votre document OpenAPI.

<div id="getting-started">
  ## Pour commencer
</div>

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

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

  <Step title="Configurez `docs.json`.">
    Mettez à jour votre `docs.json` pour référencer votre spécification OpenAPI. Ajoutez une propriété `openapi` à n’importe quel élément de navigation pour renseigner automatiquement votre documentation avec une page pour chaque endpoint défini dans votre document OpenAPI.

    Cet exemple génère une page pour chaque endpoint défini dans `openapi.json` et les organise sous le groupe « API reference » dans votre navigation.

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

    Pour générer des pages uniquement 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 des endpoints supplémentaires au tableau `pages`.

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

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

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

<ResponseField name="playground" type="object">
  Paramètres de configuration du bac à sable d’API.

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

      * `"interactive"` : afficher le bac à sable interactif.
      * `"simple"` : afficher un point de terminaison copiable sans bac à sable.
      * `"none"` : ne rien afficher.

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

    <ResponseField name="proxy" type="boolean" defaultOpen="True">
      Indique s’il faut faire transiter les requêtes d’API par un serveur proxy. Valeur par défaut : `true`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="examples" type="object">
  Paramètres de configuration pour les exemples d’API générés automatiquement.

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

      Les langages s’affichent dans l’ordre spécifié.
    </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>
  </Expandable>
</ResponseField>

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

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

Cet exemple configure le bac à sable d’API pour qu’il soit interactif, avec des extraits de code pour cURL, Python et JavaScript. Seuls les paramètres requis sont affichés dans les extraits de code.

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

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

Ces deux options vous permettent de :

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

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

Les pages `MDX` individuelles sont recommandées pour les petites API ou lorsque vous souhaitez expérimenter des modifications page par page.

Pour plus d’informations, voir [x-mint extension](/fr/api-playground/openapi-setup#x-mint-extension) et [MDX Setup](/fr/api-playground/mdx/configuration).

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

* [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.