Entrée

Sortie

C'est quoi le visualiseur GraphQL ?

Si tu as déjà collé un bout de SDL GraphQL qui est revenu sur une seule ligne en essayant de le lire, tu connais le problème. Types, champs, arguments, directives et membres d'union s'écrasent tous les uns sur les autres et la structure disparaît. Cet outil règle ça. Colle ton schéma dans le panneau de gauche et le panneau de droite te le rend avec une indentation à deux espaces, un champ par ligne, les arguments en ligne, et les descriptions en chaîne de bloc gardées au-dessus du type ou du champ qu'elles documentent.

Le formateur est fait maison — aucun paquet npm graphql n'est chargé dans la page, donc le premier rendu reste léger. Il tokenise le SDL, parcourt la structure des accolades et le ré-émet avec un espacement cohérent selon la spec GraphQL d'octobre 2021. Il gère toutes les constructions SDL qu'on croise vraiment : type, interface, union, enum, input, scalar, extend, schema, les modificateurs de liste et non-null ([Foo!]!), les valeurs par défaut, les directives et les descriptions à triples guillemets. Une entrée déjà bien formatée ressort identique.

Tout tourne dans ton navigateur. Aucun upload, aucun schéma stocké quelque part. Colle, lis, copie.

Comment utiliser le visualiseur GraphQL

Trois étapes rapides. Les boutons décrits ci-dessous sont les vrais boutons de cette page.

Colle, importe ou charge un exemple

Colle un schéma GraphQL dans le panneau Entrée à gauche. Clique sur Importer pour un fichier .graphql, .graphqls ou .gql, ou tape Exemple pour charger un schéma e-commerce réaliste. Petit aperçu de ce que donne du SDL minifié :

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]! total:Money! status:OrderStatus!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

Aussi bien les schémas style serveur (avec extend type Query) que des définitions de types autonomes fonctionnent. Les formes acceptées correspondent à ce que parsent des outils comme Apollo Server.

Lis la sortie formatée

Le panneau Sortie à droite te rend le SDL parsé avec une indentation à deux espaces. Chaque champ, valeur d'enum et membre d'union a sa propre ligne. Les arguments restent en ligne sur le champ, donc les signatures se lisent naturellement. Les descriptions écrites en chaînes de bloc ("""...""") sont gardées au-dessus du type ou champ qu'elles décrivent, ce qui est la façon recommandée par la spécification GraphQL de Relay de documenter un schéma. Si le SDL a des accolades non équilibrées ou d'autres erreurs de parsing, le visualiseur affiche un message clair plutôt que de planter.

Copie ou télécharge

Tape Copier pour récupérer le schéma formaté pour une pull request, une doc ou un chat. Tape Télécharger pour le sauver en .graphql. Le bouton effacer sur le panneau d'entrée te remet à zéro. Le parsing se fait entièrement côté client — ton schéma ne quitte jamais la page.

Quand tu vas vraiment t'en servir

Revues de pull requests de schéma

Tu reviewes un PR de schéma et le diff est dur à lire parce que le fichier est passé par un générateur de code qui a viré le formatage ? Colle la nouvelle version ici, scanne la structure des yeux, puis retourne au diff avec un modèle mental plus clair de ce qui a changé. Particulièrement utile quand l'équipe itère sur ce qui compte comme une bonne conception de schéma.

Débogage de fédération et de sous-graphes

Tu débugues un gateway de fédération Apollo et le schéma supergraph composé revient en un gros pavé ? Colle le SDL fusionné, trouve le type qui se comporte mal, vois quel sous-graphe a contribué quel champ. Les directives de fédération qui apparaissent dans la sortie sont documentées à côté du reste de la syntaxe du schéma.

Documenter une API

Tu écris la doc publique d'une API GraphQL que ton équipe maintient ? Balance le schéma dans le visualiseur, copie la version formatée dans le wiki ou le README. La forme arborescente des types, interfaces et unions se lit naturellement une fois disposée avec un champ par ligne.

Onboarder de nouveaux ingénieurs

Un nouveau coéquipier essaie d'apprendre la forme de ton API GraphQL. Un schéma formaté avec les descriptions visibles au-dessus de chaque type est un point de départ bien plus accueillant que le pavé non formaté en sortie de codegen.

Questions fréquentes

Est-ce qu'il valide mon schéma ou il le formate juste ?

Juste le formatage. Le visualiseur vérifie suffisamment l'équilibre des accolades et des guillemets pour formater, mais il ne vérifie pas que Query existe, que les types référencés sont définis, ou que les arguments de directives correspondent à leur définition. Pour une validation complète, utilise l'implémentation de référence graphql-js ou passe-le par les checks de démarrage de ton serveur.

Mon schéma est-il envoyé à un serveur ?

Non. Le formateur tourne entièrement dans ton navigateur. Rien n'est uploadé, rien n'est loggué. Tu peux coller des schémas internes ou non publiés sans souci.

Est-ce qu'il gère les descriptions en chaîne de bloc ?

Oui. Les descriptions à triples guillemets ("""Une commande passée par un client.""") sont préservées et émises sur la ligne au-dessus du type ou champ qu'elles documentent. C'est la façon canonique d'écrire de la doc SDL d'après la spec GraphQL.

Et les directives et scalaires personnalisés ?

Tous les deux sont gardés. @deprecated, @key et n'importe quelle directive custom restent en ligne sur le champ. Les scalaires custom comme scalar DateTime sont émis sur leur propre ligne. Le visualiseur n'essaie pas d'interpréter la sémantique des directives — c'est le boulot de ton serveur.

Un SDL déjà formaté va-t-il être reformaté ?

C'est idempotent — formater un SDL déjà propre produit la même sortie. Tu peux donc faire tourner le visualiseur dans un check CI ou un workflow coller-et-comparer sans te soucier de la dérive d'espaces blancs.

Quelle taille de schéma je peux coller ?

Tout ce que ton navigateur arrive à rendre confortablement. Des schémas de quelques centaines de types ne posent aucun problème. Au-delà de 5 Mo l'éditeur Ace lui-même commence à ramer — c'est lui le goulot d'étranglement, pas le parser.

Autres outils GraphQL

Visualiser n'est qu'une partie du travail avec GraphQL. Ces outils s'occupent du reste :

Visualiseur GraphQL