JSON d'introspection

GraphQL SDL

C'est quoi le convertisseur JSON d'introspection vers SDL ?

Quand vous récupérez un schéma depuis Apollo Studio, Postman, Insomnia, ou que vous lancez get-graphql-schema contre un endpoint en prod, ce que vous recevez n'est pas le SDL sympa que vous avez écrit — c'est le résultat de query { __schema { ... } } : 600+ lignes de JSON imbriqué qui décrivent chaque type, chaque champ et chaque modificateur dans un arbre d'objets kind / name / ofType. Pratique pour un outil, illisible pour un humain. Ce convertisseur prend ce JSON et le réimprime sous forme de SDL, celui que vous commiteriez vraiment dans un repo, en suivant les règles d'introspection de la spec GraphQL d'octobre 2021.

Tout se passe dans votre navigateur — pas d'envoi, pas d'IA, aucun schéma transmis nulle part. La logique de conversion reproduit ce que graphql-js fait en interne avec buildClientSchema et printSchema : parcourir l'arbre __schema, ignorer les types réservés à l'introspection (__Schema, __Type, __Field, …) et les scalaires natifs, et émettre chaque définition restante avec sa description, ses champs, ses arguments, ses valeurs par défaut et ses raisons de dépréciation intacts. Que vous colliez l'enveloppe complète { "data": { "__schema": ... } }, juste { "__schema": ... }, ou même la valeur __schema nue, la page gère les trois cas.

La sortie regroupe d'abord les scalaires, puis les enums, interfaces, unions, types d'entrée et enfin les types objet — alphabétique dans chaque groupe, indentation de deux espaces et une ligne vide entre chaque définition. Assez idempotent pour être déposé tel quel dans un fichier <code>.graphql</code> de votre repo.

Comment utiliser le convertisseur

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

Coller, importer ou charger un exemple

Collez votre JSON d'introspection dans le panneau Entrée à gauche — la conversion se fait automatiquement une fraction de seconde après que vous arrêtez de taper, donc pas de bouton Convertir à chercher. Cliquez sur Importer pour un fichier .json exporté depuis Apollo Studio ou Postman, ou tapez Exemple pour charger un résultat d'introspection réaliste Order/Customer/Money. Un coller typique commence comme ça :

{
  "data": {
    "__schema": {
      "queryType": { "name": "Query" },
      "types": [
        { "kind": "OBJECT", "name": "Order", "fields": [...] },
        ...
      ]
    }
  }
}

Vous pouvez aussi coller la valeur interne { "__schema": ... } ou l'objet __schema nu — la page essaie les trois formes. Des outils comme get-graphql-schema et l'endpoint d'introspection d'Apollo Server produisent l'une de ces formes par défaut.

Lire la sortie SDL

Le panneau Sortie à droite affiche le schéma en SDL. Chaque type a sa propre définition avec une indentation de deux espaces, les champs un par ligne, les descriptions au-dessus du type ou champ sous forme de chaînes de bloc à triple guillemets, et les raisons de dépréciation rendues comme @deprecated(reason: "..."). Les scalaires natifs et les types d'introspection __ sont filtrés — vous obtenez exactement le schéma que votre serveur publie, comme la spec GraphQL de Relay recommande de le documenter. Si le JSON est mal formé ou qu'il manque le champ __schema, vous voyez un message clair en ligne au lieu d'une stack trace.

Copier ou télécharger

Cliquez sur Copier pour récupérer le SDL pour une description de PR, une doc ou un chat. Cliquez sur Télécharger pour le sauvegarder en schema.graphql — posez-le directement dans votre repo. Le bouton effacer du panneau d'entrée vous remet à l'état vide. La conversion est entièrement côté client ; le résultat d'introspection ne quitte jamais la page.

Quand vous l'utiliseriez vraiment

Capturer un schéma depuis un endpoint en prod

Vous héritez d'un service GraphQL qui n'a aucun fichier de schéma dans le repo — juste le serveur qui tourne. Lancez une requête d'introspection, collez le JSON ici, et vous avez un schema.graphql initial commité en cinq minutes. Plus simple que de câbler buildClientSchema et printSchema depuis graphql-js juste pour le faire une seule fois.

Lire un export Apollo Studio ou Postman

L'export de schéma depuis Apollo Studio, c'est du JSON d'introspection. Pareil pour le bouton "Save schema" de Postman sur une requête GraphQL. Convertissez ici et vous pouvez vraiment parcourir le schéma dans un éditeur de code au lieu de plisser les yeux sur du JSON.

Diff entre deux snapshots d'un schéma en prod

Lancez l'introspection contre staging et prod, convertissez chacun en SDL, puis faites un diff entre les deux fichiers. Repérer un champ manquant ou une valeur d'enum renommée est trivial en SDL et à peu près impossible en JSON d'introspection brut.

Générer des stubs de types pour un service qui n'est pas le vôtre

Besoin de types TypeScript ou de hooks React pour une API GraphQL tierce ? La plupart des générateurs de code veulent du SDL, pas du JSON d'introspection. Convertissez ici, puis envoyez le SDL dans votre pipeline de codegen — graphql-react, graphql-codegen, ou ce que votre stack utilise.

Questions courantes

Est-ce qu'il faut l'enveloppe complète { "data": { "__schema": ... } } ?

Non. La page accepte trois formes : l'enveloppe de réponse GraphQL complète, juste { "__schema": ... }, ou même l'objet __schema nu. Quelle que soit celle que vous collez, elle trouve la racine __schema et travaille à partir de là.

Et si mon JSON n'a pas de champ __schema ?

Vous recevez un message clair : "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." Pas de crash, pas de stack trace.

Les descriptions et raisons de dépréciation sont-elles préservées ?

Oui. Les descriptions de types et de champs sont émises sous forme de chaînes de bloc à triple guillemets au-dessus de la définition. Les champs et valeurs d'enum dépréciés reçoivent @deprecated(reason: "...") sur la même ligne. Cela correspond à la sortie de printSchema de graphql-js.

Et les scalaires natifs et les types d'introspection __ ?

Filtrés. String, Int, Float, Boolean et ID sont implicites en SDL — ils n'apparaissent que dans les types de champs, pas comme définitions de premier niveau. Pareil pour __Schema, __Type, __Field et le reste des méta-types d'introspection.

La sortie est-elle garantie de revenir au même résultat d'introspection ?

Sémantiquement, oui — le SDL décrit le même schéma. Octet pour octet, non, parce que l'ordre des types et des champs peut différer de votre fichier source d'origine. La sortie est triée alphabétiquement dans chaque groupe de définitions pour des diffs stables.

Mon résultat d'introspection est-il envoyé à un serveur ?

Non. La conversion tourne entièrement dans votre navigateur. Rien n'est envoyé, rien n'est loggé. Vous pouvez coller sans crainte des schémas de services internes ou pas encore lancés.

Autres outils GraphQL

Une fois que vous avez le SDL, ceux-là s'occupent du reste :

JSON d'introspection vers GraphQL SDL