Créer manuellement des pages d'API

Configurez les paramètres de votre API

Dans votre fichier docs.json, définissez votre URL de base et votre méthode d’authentification.

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

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

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>

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 :

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

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

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