# Créer manuellement des pages d'API (/fr/api-playground/mdx-setup)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 2131 · updated: 2026-07-30 -->
Related: [Playground](/fr/api-playground/overview.md), [Configuration d’OpenAPI](/fr/api-playground/openapi-setup.md), [Types de données complexes](/fr/api-playground/complex-data-types.md), [Ajouter des exemples de SDK](/fr/api-playground/adding-sdk-examples.md), [Gérer la visibilité des pages](/fr/api-playground/managing-page-visibility.md), [Réponses multiples](/fr/api-playground/multiple-responses.md)

Vous pouvez définir manuellement des endpoints d'API dans des pages MDX individuelles. Cette approche est particulièrement utile pour de petites API ou pour le prototypage.

<div id="setup">
  ## Configuration [#configuration]
</div>

<Steps>
  <Step title="Configurez les paramètres de votre API">
    Dans votre fichier `docs.json`, définissez votre URL de base et votre méthode d’authentification.

    ```json title="Example docs.json"
    "api": {
      "mdx": {
        "server": "https://api.acme.com/",
        "auth": {
          "method": "key",
          "name": "x-api-key"
        }
      }
    }
    ```

    Si vous souhaitez masquer le bac à sable d’API, définissez le champ `display` sur `none`. Vous n’avez pas besoin d’inclure de méthode d’authentification si vous masquez le bac à sable d’API.

    ```json
    "api": {
      "playground": {
        "display": "none"
      }
    }
    ```

    Consultez la liste complète des configurations d’API dans [Settings](/fr/organize/settings-api).
  </Step>

  <Step title="Créez les pages de vos endpoints">
    Créez un fichier MDX pour chaque endpoint. Définissez les champs `title` et `api` dans le frontmatter :

    ```mdx
    ---
    title: 'Créer un nouvel utilisateur'
    api: 'POST /v1/users'
    ---
    ```

    Le champ de frontmatter `api` accepte soit une URL complète, soit un chemin relatif :

    * **URL complète** comme `POST https://api.acme.com/v1/users`. Le champ `server` dans `docs.json` est ignoré pour cet endpoint.
    * **Chemin relatif** comme `POST /v1/users`. Nécessite un champ `server` dans `docs.json`. L’URL du serveur est préfixée au chemin.

    Spécifiez les paramètres de chemin en les entourant de `{}` :

    ```bash
    https://api.example.com/v1/endpoint/{userId}
    ```

    Pour surcharger le mode d'affichage global du playground pour une page spécifique, ajoutez `playground` au frontmatter :

    ```mdx
    ---
    title: 'Créer un nouvel utilisateur'
    api: 'POST https://api.mintlify.com/user'
    playground: 'none'
    ---
    ```

    Options :

    * `playground: 'interactive'` - Afficher le playground interactif (par défaut)
    * `playground: 'simple'` - Afficher un endpoint copiable sans playground
    * `playground: 'none'` - Masquer le playground entièrement
  </Step>

  <Step title="Ajouter des paramètres et des réponses">
    Utilisez les [champs de paramètres et de réponse](/fr/components/fields) pour documenter les paramètres et les valeurs renvoyées par votre endpoint.

    ```mdx
    <ParamField path="userId" type="string" required>
      Identifiant unique de l'utilisateur
    </ParamField>

    <ParamField body="email" type="string" required>
      Adresse e-mail de l'utilisateur
    </ParamField>

    <ResponseField name="id" type="string" required>
      Identifiant unique de l'utilisateur nouvellement créé
    </ResponseField>

    <ResponseField name="email" type="string" required>
      Adresse e-mail de l'utilisateur
    </ResponseField>
    ```
  </Step>

  <Step title="Ajoutez vos points de terminaison d’API à votre documentation">
    Ajoutez vos pages d’endpoint à la navigation en mettant à jour le champ `pages` de votre fichier `docs.json` :

    ```json title="docs.json"
    "navigation": {
      "tabs": [
        {
          "tab": "Référence de l'API",
          "groups": [
            {
              "group": "Users",
              "pages": [
                "api-reference/users/create-user",
                "api-reference/users/get-user",
                "api-reference/users/update-user"
              ]
            },
            {
              "group": "Orders",
              "pages": [
                "api-reference/orders/create-order",
                "api-reference/orders/list-orders"
              ]
            }
          ]
        }
      ]
    }
    ```

    Chaque chemin de page correspond à un fichier MDX dans votre référentiel de documentation. Par exemple, `api-reference/users/create-user.mdx`. Pour en savoir plus sur la structuration de votre documentation, consultez [Navigation](/fr/organize/navigation).

    ### Utiliser des endpoints OpenAPI dans la navigation [#utiliser-des-endpoints-openapi-dans-la-navigation]

    Si vous disposez d’une spécification OpenAPI, vous pouvez faire référence à des endpoints directement dans votre navigation sans créer de fichiers MDX individuels. Faites référence à des endpoints spécifiques en incluant le chemin du fichier OpenAPI et l’endpoint :

    ```json title="docs.json"
    "navigation": {
      "pages": [
        "introduction",
        "/path/to/users-openapi.json POST /users",
        "/path/to/orders-openapi.json GET /orders"
      ]
    }
    ```

    Vous pouvez également définir une spécification OpenAPI par défaut pour un groupe de navigation et y référencer les endpoints par méthode et par chemin :

    ```json title="docs.json"
    {
      "group": "Référence de l'API",
      "openapi": "/path/to/openapi-v1.json",
      "pages": [
        "overview",
        "authentication",
        "GET /users",
        "POST /users",
        {
          "group": "Orders",
          "openapi": "/path/to/openapi-v2.json",
          "pages": [
            "GET /orders",
            "POST /orders"
          ]
        }
      ]
    }
    ```

    Pour plus de détails sur l'intégration OpenAPI, consultez la page [Configuration OpenAPI](/fr/api-playground/openapi-setup).
  </Step>
</Steps>

<div id="enable-authentication">
  ## Activer l’authentification [#activer-lauthentification]
</div>

Vous pouvez configurer l’authentification globalement dans `docs.json`, ou la surcharger sur des pages spécifiques à l’aide du champ `authMethod` dans le frontmatter. Une méthode définie au niveau d’une page prend le pas sur le paramètre global.

<div id="bearer-token">
  ### Jeton d’authentification Bearer [#jeton-dauthentification-bearer]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="docs.json" groupId="docs-json+page-metadata">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="docs.json">
        docs.json
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Page Metadata">
        Page Metadata
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="docs.json">
      ```json  
      "api": {
        "mdx": {
          "auth": {
            "method": "bearer"
          }
        }
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Page Metadata">
      ```mdx  
      ---
      title: "Titre de votre page"
      authMethod: "bearer"
      ---
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="basic-authentication">
  ### Authentification basique [#authentification-basique]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="docs.json" groupId="docs-json+page-metadata">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="docs.json">
        docs.json
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Page Metadata">
        Page Metadata
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="docs.json">
      ```json  
      "api": {
        "mdx": {
          "auth": {
            "method": "basic"
          }
        }
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Page Metadata">
      ```mdx  
      ---
      title: "Titre de votre page"
      authMethod: "basic"
      ---
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="api-key">
  ### Clé API [#clé-api]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="docs.json" groupId="docs-json+page-metadata">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="docs.json">
        docs.json
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Page Metadata">
        Page Metadata
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="docs.json">
      ```json  
      "api": {
        "mdx": {
          "auth": {
            "method": "key",
            "name": "x-api-key"
          }
        }
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Page Metadata">
      ```mdx  
      ---
      title: "Titre de la page"
      authMethod: "key"
      ---
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="none">
  ### Aucun [#aucun]
</div>

Pour désactiver l’authentification sur une page spécifique, définissez `authMethod` sur `none` :

```mdx title="Page Metadata"
---
title: "Titre de votre page"
authMethod: "none"
---
```