Passer au contenu principal

​
Ajouter un schéma GraphQL

Pour créer des pages pour votre API GraphQL, vous avez besoin d’un schéma GraphQL valide au format SDL (Schema Definition Language). Stockez le schéma dans votre dépôt de documentation ou hébergez-le à une URL HTTPS que Mintlify peut récupérer.
schema.graphql

​
Remplir automatiquement les pages GraphQL

Pour générer automatiquement des pages pour chaque requête, mutation et type de votre schéma, ajoutez une propriété graphql à un onglet ou à un groupe dans votre docs.json. Mintlify analyse le schéma et crée une page pour chaque opération et chaque type nommé.
La propriété graphql accepte soit une chaîne (un chemin local ou une URL HTTPS), soit un objet avec les champs suivants :
Vous pouvez déclarer graphql uniquement sur un onglet ou un groupe.Un onglet avec graphql peut inclure des groups, mais aucune autre structure de navigation, comme pages, versions ou languages.Un groupe avec graphql peut inclure des pages.
​
string
requis
Un chemin local vers un fichier SDL dans votre dépôt de documentation ou une URL HTTPS vers un fichier SDL hébergé. Les URL HTTP ne sont pas acceptées.
​
string
Le répertoire dans lequel les pages générées sont placées. Par défaut, graphql-reference.

​
Pages générées

Mintlify organise les pages générées en trois sections sous l’onglet ou le groupe que vous avez configuré :
  • Queries — une page par champ de votre type racine Query.
  • Mutations — une page par champ de votre type racine Mutation.
  • Types — une page par type nommé (object, input, enum, interface ou union).
Sur un onglet, les sections apparaissent après les groupes que vous définissez. Sur un groupe, elles apparaissent sous forme de groupes imbriqués après les pages que vous listez. Chaque page d’opération affiche la description du champ, les arguments, le type de retour et des liens vers tous les types référencés. Les pages de requêtes et de mutations comprennent également un exemple d’opération généré, les variables requises et un exemple de réponse JSON. Les pages de types affichent la définition du schéma en lecture seule, avec des types de champs liés afin que les lecteurs puissent naviguer dans le graphe.

​
Sélectionner des opérations et des types spécifiques

Pour créer une référence sélectionnée au lieu de générer toutes les pages, listez des sélecteurs dans le tableau pages d’un groupe qui déclare graphql. Vous pouvez également les lister dans tout groupe imbriqué sous un onglet ou un groupe qui déclare graphql. Les onglets avec graphql ne peuvent pas inclure de pages : placez donc les sélecteurs dans un groupe à l’intérieur de l’onglet. Mintlify génère une page uniquement pour chaque opération ou type sélectionné.
Un sélecteur est un type suivi d’un nom, séparés par un espace :
  • QUERY <field> : un champ de votre type racine Query.
  • MUTATION <field> : un champ de votre type racine Mutation.
  • TYPE <name> : un type nommé : object, input, enum, interface ou union.
Les types de sélecteur doivent être en majuscules. Utilisez un chemin avec des points, comme MUTATION cart.createCart, pour sélectionner une opération imbriquée sous un champ d’espace de noms. Les sélecteurs TYPE n’acceptent pas les chemins avec des points. La barre latérale affiche une opération imbriquée avec son dernier segment : MUTATION cart.createCart apparaît donc comme createCart. L’URL de la page conserve le chemin complet et se termine par cart/createCart. Si une page d’un onglet ou d’un groupe avec graphql est un sélecteur, Mintlify ne génère pas les sections complètes Queries, Mutations et Types pour cet élément. Les chemins de page classiques du même tableau pages fonctionnent normalement. Dans une référence sélective, les pages de requêtes et de mutations ne renvoient qu’aux pages de types générées par vos sélecteurs. Pour créer un lien vers un type référencé par une opération sélectionnée, ajoutez un sélecteur TYPE pour ce type. Si un sélecteur ne correspond à rien dans votre schéma, la compilation échoue avec une erreur qui indique l’opération ou le type manquant.

​
Dépréciations

Les champs et les arguments marqués avec @deprecated dans votre schéma sont signalés comme dépréciés sur les pages générées. La raison de la dépréciation, lorsqu’elle est fournie, apparaît à côté du champ.

​
Mettre à jour votre documentation

Mintlify régénère les pages de référence GraphQL lorsque vous exécutez mint dev ou lorsque vous poussez des modifications vers votre dépôt de documentation. Si votre schéma est hébergé à une URL HTTPS, les mises à jour du schéma sont prises en compte lors de la prochaine build.

Sujets connexes

Migrer depuis une autre plateformeSEORéférence des commandes de la CLI Mintlify