Passer au contenu principal
Vous pouvez définir manuellement des endpoints d’API dans des fichiers MDX individuels plutôt que d’utiliser une spécification OpenAPI. Cette méthode offre de la flexibilité pour du contenu personnalisé, mais nous recommandons de générer la documentation d’API à partir d’un fichier de spécification OpenAPI pour la plupart des projets, car elle est plus facile à maintenir et plus riche en fonctionnalités. Toutefois, créer des pages MDX pour une API peut être utile pour documenter de petites API ou pour du prototypage. Pour générer des pages pour des endpoints d’API avec MDX, configurez vos paramètres d’API dans docs.json, créez des fichiers MDX individuels pour chaque endpoint et utilisez des composants comme <ParamFields /> pour définir les paramètres. À partir de ces définitions, Mintlify génère des terrains de jeu API interactifs, des exemples de requêtes et des exemples de réponses.
1

Configurer votre API

Dans votre fichier docs.json, définissez votre URL de base et la méthode d’authentification :
 "api": {
  "mdx": {
    "server": "https://mintlify.com/api", // string array for multiple base URLs
    "auth": {
      "method": "key",
      "name": "x-api-key" // options: bearer, basic, key.
    }
  }
}
Si vous souhaitez masquer le terrain de jeu API, utilisez le champ display. Vous n’avez pas besoin d’inclure une méthode d’authentification si vous masquez le terrain de jeu.
"api": {
  "playground": {
    "display": "none"
  }
}
Retrouvez la liste complète des configurations d’API dans Paramètres.
2

Créer vos pages d’endpoint

Chaque page d’endpoint d’API doit avoir un fichier MDX correspondant. En haut de chaque fichier, définissez title et api :
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
---
Vous pouvez spécifier des paramètres de chemin en ajoutant le nom du paramètre au chemin, entouré 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.
Vous pouvez remplacer le mode d’affichage défini globalement pour le terrain de jeu API sur une page en ajoutant playground au front matter :
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
  • playground: 'interactive' - Afficher le terrain de jeu interactif.
  • playground: 'simple' - Afficher un endpoint copiable sans terrain de jeu.
  • playground: 'none' - Masquer le terrain de jeu.
3

Ajouter vos endpoints à votre documentation

Ajoutez vos pages d’endpoint à la barre latérale en ajoutant les chemins dans le champ navigation de votre docs.json. En savoir plus sur la structuration de votre documentation dans Navigation.

​
Activer l’authentification

Vous pouvez ajouter une méthode d’authentification à votre docs.json pour l’activer globalement sur toutes les pages, ou la définir au cas par cas. La méthode d’authentification d’une page remplace la méthode globale si les deux sont définies.

​
Jeton Bearer

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

​
Authentification Basic

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

​
Clé API

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

​
Aucune

La méthode d’authentification none est utile pour désactiver l’authentification sur un endpoint spécifique après avoir défini une valeur par défaut dans docs.json. 
---
title: "Your page title"
authMethod: "none"
---