Passer au contenu principal
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.

​
Configuration

1

Configurez les paramètres de votre API

Dans votre fichier docs.json, définissez votre URL de base et votre méthode d’authentification.
"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.
"api": {
  "playground": {
    "display": "none"
  }
}
Consultez la liste complète des configurations d’API dans Settings.
2

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 :
---
title: 'Créer un nouvel utilisateur'
api: 'POST https://api.mintlify.com/user'
---
Spécifiez les paramètres de chemin en les entourant de {} :
https://api.example.com/v1/endpoint/{userId}
Si vous avez un champ server configuré dans docs.json, vous pouvez utiliser des chemins relatifs comme /v1/endpoint.
Pour surcharger le mode d’affichage global du playground pour une page spécifique, ajoutez playground au frontmatter :
---
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
3

Ajouter des paramètres et des réponses

Utilisez les champs de paramètres et de réponse pour documenter les paramètres et les valeurs renvoyées par votre endpoint.
<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>
4

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 :
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.

​
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 :
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 :
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’intégration OpenAPI, consultez la page Configuration OpenAPI.

​
Activer l’authentification

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.

​
Jeton d’authentification Bearer

"api": {
  "mdx": {
    "auth": {
      "method": "bearer"
    }
  }
}

​
Authentification basique

"api": {
  "mdx": {
    "auth": {
      "method": "basic"
    }
  }
}

​
Clé API

"api": {
  "mdx": {
    "auth": {
      "method": "key",
      "name": "x-api-key"
    }
  }
}

​
Aucun

Pour désactiver l’authentification sur une page spécifique, définissez authMethod sur none :
Page Metadata
---
title: "Titre de votre page"
authMethod: "none"
---