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 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", // string array for multiple base URLs
    "auth": {
      "method": "key",
      "name": "x-api-key" // options: bearer, basic, key.
    }
  }
}
Si vous souhaitez masquer le bac à sable 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 les pages de vos 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 donnée, le mode d’affichage du bac à sable API défini globalement en ajoutant playground au front matter :
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
  • playground: 'interactive' - Afficher le bac à sable interactif.
  • playground: 'simple' - Afficher un endpoint copiable sans bac à sable.
  • playground: 'none' - Masquer le bac à sable.
3

Ajoutez vos endpoints à votre documentation

Ajoutez les pages d’endpoint à la barre latérale en renseignant leurs 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 aura priorité sur la méthode globale si les deux sont définies.

​
Jeton Bearer

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

​
Authentification de base

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