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

# Playground

> Permettez aux développeurs de tester des endpoints d’API directement dans votre documentation.

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

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/anotherhorizon/KtT4EXjd_91dkOA7/images/playground/API-playground-light.png?fit=max&auto=format&n=KtT4EXjd_91dkOA7&q=85&s=0909a73e38e7335a50ed3a5624ebe5fd" 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/anotherhorizon/KtT4EXjd_91dkOA7/images/playground/API-playground-dark.png?fit=max&auto=format&n=KtT4EXjd_91dkOA7&q=85&s=8492d21541faedb47f23bde5a03c2ae6" 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 openapi-check <filename>`.
    </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;">
      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.

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

    <ResponseField name="proxy" type="boolean" defaultOpen="True">
      Indique s’il faut faire passer les requêtes API via un serveur proxy. Valeur par défaut : `true`.
    </ResponseField>
  </Expandable>
</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é.
    </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>
  </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. Seuls les paramètres requis sont affichés dans les extraits, 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="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

L’extension `x-mint` est recommandée 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.

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

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

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