Dépannage

Problèmes courants liés aux références API

Si vos pages d’API ne s’affichent pas correctement, vérifiez d’abord ces problèmes de configuration courants :

All of my OpenAPI pages are completely blank

Dans ce scénario, il est probable que Mintlify ne parvienne pas à trouver votre document OpenAPI, ou que votre document OpenAPI soit invalide.

Exécuter mint dev en local devrait révéler certains de ces problèmes.

Pour vérifier que votre document OpenAPI passe la validation :

1. Rendez-vous sur ce validateur
2. Ouvrez l’onglet « Validate text »
3. Collez votre document OpenAPI
4. Cliquez sur « Validate it! »

Si la zone de texte qui s’affiche en dessous a une bordure verte, votre document a passé la validation. Il s’agit du même package de validation que celui utilisé par Mintlify pour valider les documents OpenAPI ; si votre document passe la validation ici, il y a de fortes chances que le problème se situe ailleurs.

Par ailleurs, Mintlify ne prend pas en charge OpenAPI 2.0. Si votre document utilise cette version de la spécification, vous pourriez rencontrer ce problème. Vous pouvez convertir votre document sur editor.swagger.io (menu Edit > Convert to OpenAPI 3) :

One of my OpenAPI pages is completely blank

C’est généralement dû à une faute de frappe dans le champ openapi des métadonnées de la page. Assurez-vous que la méthode HTTP et le chemin correspondent exactement à la méthode HTTP et au chemin dans le document OpenAPI.

Voici un exemple de ce qui peut poser problème :

get-user.mdx

---
openapi: "GET /users/{id}/"
---

openapi.yaml

paths:
  "/users/{id}":
    get: ...

Notez que le chemin dans le champ openapi se termine par une barre oblique, alors que le chemin dans le document OpenAPI n’en a pas.

Un autre problème courant est un nom de fichier mal orthographié. Si vous spécifiez un document OpenAPI particulier dans le champ openapi, assurez-vous que le nom de fichier est correct. Par exemple, si vous avez deux documents OpenAPI openapi/v1.json et openapi/v2.json, vos métadonnées pourraient ressembler à ceci :

api-reference/v1/users/get-user.mdx

---
openapi: "v1 GET /users/{id}"
---

Requests from the API Playground don't work

Si vous utilisez un domaine personnalisé, le problème peut venir de votre reverse proxy. Par défaut, les requêtes effectuées via le Bac à sable API commencent par une requête POST vers le chemin /_mintlify/api/request sur le site de documentation. Si votre reverse proxy n’autorise que les requêtes GET, alors toutes ces requêtes échoueront. Pour corriger cela, configurez votre reverse proxy pour autoriser les requêtes POST vers le chemin /_mintlify/api/request.

Sinon, si votre reverse proxy ne permet pas d’accepter des requêtes POST, vous pouvez configurer Mintlify pour envoyer les requêtes directement à votre backend avec le paramètre api.playground.proxy dans docs.json, comme décrit dans la documentation des paramètres. Avec cette configuration, vous devrez activer CORS sur votre serveur, puisque les requêtes proviendront directement des navigateurs des utilisateurs plutôt que de passer par votre proxy.

OpenAPI navigation entries are not generating pages

Si vous utilisez une configuration de navigation OpenAPI mais que les pages ne sont pas générées, vérifiez ces problèmes courants :

1. Spécification OpenAPI par défaut manquante : Assurez-vous d’avoir un champ openapi défini pour l’élément de navigation :

"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "GET /users",
        "POST /users"
      ]
    }
  ]
}

2. Héritage de la spécification OpenAPI : Si vous utilisez une navigation imbriquée, assurez-vous que les groupes enfants héritent de la bonne spécification OpenAPI ou définissent la leur.

3. Problèmes de validation : Utilisez mint openapi-check <path-to-openapi-file> pour vérifier que votre document OpenAPI est valide.

Some OpenAPI operations appear in navigation but others don't

1. Opérations cachées : Les opérations marquées avec x-hidden: true dans votre spécification OpenAPI n’apparaîtront pas dans la navigation générée automatiquement.
2. Opérations invalides : Les opérations comportant des erreurs de validation dans la spécification OpenAPI peuvent être ignorées. Vérifiez votre document OpenAPI pour détecter d’éventuelles erreurs de syntaxe.
3. Inclusion manuelle vs automatique : Si vous référencez des endpoints à partir d’une spécification OpenAPI, seules les opérations explicitement référencées apparaîtront dans la navigation. Aucune autre page ne sera ajoutée automatiquement. Cela inclut les opérations référencées dans des éléments de navigation enfants.

Mixed navigation (OpenAPI and MDX pages) not working correctly

Lors de la combinaison d’opérations OpenAPI avec des pages de documentation classiques dans la navigation :

1. Conflits de fichiers : vous ne pouvez pas avoir à la fois un fichier MDX et une entrée de navigation pour la même opération. Par exemple, si vous avez get-users.mdx, n’incluez pas également “GET /users” dans votre navigation. Si vous devez avoir un fichier qui partage un nom avec une opération, utilisez l’extension x-mint pour le point de terminaison afin que le href pointe vers un autre emplacement.
2. Résolution des chemins : les entrées de navigation qui ne correspondent pas à des opérations OpenAPI seront traitées comme des chemins de fichiers. Assurez-vous que vos fichiers MDX existent aux emplacements attendus.
3. Sensibilité à la casse : la correspondance des opérations OpenAPI est sensible à la casse. Assurez-vous que les méthodes HTTP sont en majuscules dans les entrées de navigation.