Créer manuellement des pages d'API

Créez manuellement des pages de référence d’API avec des fichiers MDX pour un contrôle total sur la mise en page des petites API, prototypes ou docs personnalisées.

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.

   Example docs.json

   "api": {
     "mdx": {
       "server": "https://api.acme.com/",
       "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 /v1/users'
   ---
   

   Le champ de frontmatter api accepte soit une URL complète, soit un chemin relatif :

   • URL complète comme POST https://api.acme.com/v1/users. Le champ server dans docs.json est ignoré pour cet endpoint.
   • Chemin relatif comme POST /v1/users. Nécessite un champ server dans docs.json. L’URL du serveur est préfixée au chemin.

   Spécifiez les paramètres de chemin en les entourant de {} :

   https://api.example.com/v1/endpoint/{userId}
   

   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": "Users",
             "pages": [
               "api-reference/users/create-user",
               "api-reference/users/get-user",
               "api-reference/users/update-user"
             ]
           },
           {
             "group": "Orders",
             "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": [
       "overview",
       "authentication",
       "GET /users",
       "POST /users",
       {
         "group": "Orders",
         "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

docs.json

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

​

Authentification basique

docs.json

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

​

Clé API

docs.json

"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"
---