mintlify__docs/fr/api-playground/mdx-setup.mdx

---
title: "Créer manuellement des pages d'API"
description: "Documentez manuellement les endpoints d'API avec des fichiers MDX."
keywords: ["documentation d'API", "documentation d'endpoint"]
---

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
</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
    "api": {
      "mdx": {
        "server": "https://mintlify.com/api",
        "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-configurations).
  </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 https://api.mintlify.com/user'
    ---
    ```

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

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

    <Tip>
      Si vous avez un champ `server` configuré dans `docs.json`, vous pouvez utiliser des chemins relatifs comme `/v1/endpoint`.
    </Tip>

    Pour surcharger le mode d&#39;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 docs.json
    "navigation": {
      "tabs": [
        {
          "tab": "Référence de l'API",
          "groups": [
            {
              "group": "Utilisateurs",
              "pages": [
                "api-reference/users/create-user",
                "api-reference/users/get-user",
                "api-reference/users/update-user"
              ]
            },
            {
              "group": "Commandes",
              "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

    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 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 docs.json
    {
      "group": "Référence de l'API",
      "openapi": "/path/to/openapi-v1.json",
      "pages": [
        "apercu",
        "authentification",
        "GET /users",
        "POST /users",
        {
          "group": "Commandes",
          "openapi": "/path/to/openapi-v2.json",
          "pages": [
            "GET /orders",
            "POST /orders"
          ]
        }
      ]
    }
    ```

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

<div id="enable-authentication">
  ## Activer l’authentification
</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
</div>

<CodeGroup>
  ```json docs.json
  "api": {
    "mdx": {
      "auth": {
        "method": "bearer"
      }
    }
  }
  ```

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

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

<CodeGroup>
  ```json docs.json
  "api": {
    "mdx": {
      "auth": {
        "method": "basic"
      }
    }
  }
  ```

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

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

<CodeGroup>
  ```json docs.json
  "api": {
    "mdx": {
      "auth": {
        "method": "key",
        "name": "x-api-key"
      }
    }
  }
  ```

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

<div id="none">
  ### Aucun
</div>

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

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