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. Cependant, 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 bacs à sable d’API interactifs, des exemples de requêtes et des exemples de réponses.
1

Configurez 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", // tableau de chaînes pour plusieurs URL de base
    "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éez vos pages d’endpoints

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, pour une page, le mode d’affichage globalement défini pour le 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

Ajoutez vos endpoints à votre documentation

Ajoutez vos pages d’endpoints à la barre latérale en ajoutant les chemins dans le champ navigation de votre docs.json. Pour en savoir plus sur la structuration de votre documentation, consultez 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 page par page. La méthode d’authentification d’une page remplacera la méthode globale si les deux sont définies.

​
Jeton d’authentification Bearer

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

​
Authentification de base

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

​
Clé d’API

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

​
None

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