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 séparés 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 bacs à sable d’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 bac à sable d’API, utilisez le champ display. Vous n’avez pas besoin d’inclure une méthode d’authentification si vous masquez le bac à sable.
"api": {
  "playground": {
    "display": "none"
  }
}
Retrouvez la liste complète des configurations d’API dans Settings.
2

Créer les pages de vos endpoints

Chaque 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, entre {} :
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, pour une page donnée, le mode d’affichage global du bac à sable d’API en ajoutant playground au frontmatter :
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
  • playground: 'interactive' - Affiche le bac à sable interactif.
  • playground: 'simple' - Affiche un endpoint copiable sans bac à sable.
  • playground: 'none' - Masque le bac à sable.
3

Ajouter vos endpoints à votre documentation

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

​
Activation de l’authentification

Vous pouvez ajouter une méthode d’authentification à votre fichier docs.json pour l’activer globalement sur chaque page, ou la définir au niveau de chaque page. La méthode d’authentification définie sur une page remplace la méthode globale si les deux sont configurées.

​
Jeton Bearer

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

​
Authentification Basic

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

​
Clé d’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 point de terminaison spécifique après avoir défini une valeur par défaut dans docs.json. 
---
title: "Your page title"
authMethod: "none"
---
⌘I