JSON de introspecção

GraphQL SDL

O que é o conversor de JSON de introspecção para SDL?

Quando você puxa um schema do Apollo Studio, Postman, Insomnia, ou roda get-graphql-schema contra um endpoint em produção, o que volta não é o SDL amigável que você escreveu — é o resultado de query { __schema { ... } }: mais de 600 linhas de JSON aninhado descrevendo cada tipo, cada campo e cada modificador numa árvore de objetos kind / name / ofType. Útil para uma ferramenta, ilegível para um humano. Esse conversor pega esse JSON e imprime de volta como o SDL que você de fato comitaria num repositório, seguindo as regras de introspecção da spec do GraphQL de outubro de 2021.

Tudo acontece no seu navegador — sem upload, sem IA, nenhum schema enviado a lugar algum. A lógica de conversão espelha o que o graphql-js faz internamente com buildClientSchema e printSchema: percorrer a árvore __schema, pular os tipos exclusivos da introspecção (__Schema, __Type, __Field, …) e os escalares embutidos, e emitir cada definição restante com sua descrição, campos, argumentos, valores padrão e razões de depreciação intactos. Seja colando o envelope completo { "data": { "__schema": ... } }, só { "__schema": ... }, ou até o valor __schema sozinho, a página dá conta dos três casos.

A saída agrupa primeiro escalares, depois enums, interfaces, unions, tipos de input e por fim tipos objeto — alfabético dentro de cada grupo, com indentação de dois espaços e uma linha em branco entre definições. Idempotente o suficiente para soltar direto num arquivo <code>.graphql</code> do seu repo.

Como usar o conversor

Três passos. Os botões abaixo são os botões reais desta página.

Colar, enviar ou carregar um exemplo

Cole seu JSON de introspecção no painel Entrada à esquerda — a conversão acontece automaticamente uma fração de segundo depois de você parar de digitar, então não tem botão Convert para procurar. Clique em Enviar para um arquivo .json exportado do Apollo Studio ou Postman, ou aperte Exemplo para carregar um resultado de introspecção realista de Order/Customer/Money. Um colar típico começa assim:

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

Você também pode colar o valor interno { "__schema": ... } ou o objeto __schema sozinho — a página tenta as três formas. Ferramentas como o get-graphql-schema e o endpoint de introspecção do Apollo Server produzem uma dessas formas por padrão.

Ler a saída SDL

O painel Saída à direita renderiza o schema como SDL. Cada tipo fica na sua própria definição com indentação de dois espaços, campos um por linha, descrições mantidas acima do tipo ou campo como strings de bloco com aspas triplas, e razões de depreciação renderizadas como @deprecated(reason: "..."). Os escalares embutidos e os tipos de introspecção __ são filtrados — o que você recebe é exatamente o schema que seu servidor publica, do jeito que a spec do GraphQL do Relay recomenda documentar. Se o JSON estiver malformado ou faltando o campo __schema, você recebe uma mensagem inline amigável em vez de uma stack trace.

Copiar ou baixar

Aperte Copiar para pegar o SDL para a descrição de um PR, doc ou chat. Aperte Baixar para salvar como schema.graphql — solte direto no seu repo. O botão de limpar do painel de entrada te leva de volta ao estado em branco. A conversão é totalmente client-side; o resultado de introspecção nunca sai da página.

Quando você realmente usaria isso

Capturar um schema de um endpoint em produção

Você herda um serviço GraphQL que não tem arquivo de schema no repo — só o servidor rodando. Roda uma consulta de introspecção, cola o JSON aqui, e em cinco minutos tem um schema.graphql inicial comitado. Mais fácil do que ligar buildClientSchema e printSchema do graphql-js só pra fazer isso uma vez.

Ler uma exportação do Apollo Studio ou Postman

A exportação de schema do Apollo Studio é o JSON de introspecção. O mesmo para o botão "Save schema" do Postman numa request GraphQL. Converta aqui e dá pra realmente passar o olho no schema num editor de código em vez de ficar apertando os olhos no JSON.

Diff entre dois snapshots de um schema em produção

Roda introspecção contra staging e produção, converte cada um pra SDL, e dá um diff nos dois arquivos. Achar um campo faltando ou um valor de enum renomeado é trivial em SDL e basicamente impossível em JSON de introspecção cru.

Gerar stubs de tipo de um serviço que não é seu

Precisa de tipos TypeScript ou hooks React para uma API GraphQL de terceiros? A maioria dos geradores de código quer SDL, não JSON de introspecção. Converte aqui, e depois manda o SDL pro seu pipeline de codegen — graphql-react, graphql-codegen, ou o que sua stack usar.

Perguntas frequentes

Precisa do envelope completo { "data": { "__schema": ... } }?

Não. A página aceita três formas: o envelope completo de resposta GraphQL, só { "__schema": ... }, ou até o objeto __schema sozinho. Qualquer que seja a que você cole, ela acha a raiz __schema e trabalha a partir daí.

E se meu JSON não tiver o campo __schema?

Você recebe uma mensagem amigável: "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." Sem crash, sem stack trace.

Descrições e razões de depreciação são preservadas?

Sim. Descrições de tipo e campo são emitidas como strings de bloco com aspas triplas acima da definição. Campos e valores de enum depreciados ganham @deprecated(reason: "...") na mesma linha. Isso bate com a saída do printSchema do graphql-js.

E quanto aos escalares embutidos e os tipos de introspecção __?

Filtrados. String, Int, Float, Boolean e ID são implícitos no SDL — só aparecem em tipos de campo, não como definições de topo. O mesmo para __Schema, __Type, __Field e o resto dos meta-tipos de introspecção.

A saída garante voltar ao mesmo resultado de introspecção?

Semanticamente, sim — o SDL descreve o mesmo schema. Byte por byte, não, porque a ordem dos tipos e campos pode diferir do seu arquivo fonte original. A saída é alfabetizada dentro de cada grupo de definições para diffs estáveis.

Meu resultado de introspecção é enviado para um servidor?

Não. A conversão roda inteiramente no seu navegador. Nada é enviado, nada é registrado. Seguro pra colar schemas de serviços internos ou ainda não lançados.

Outras ferramentas GraphQL

Depois que você tem o SDL, essas resolvem o resto:

JSON de introspecção para GraphQL SDL