Entrada

Saída

O que é o Visualizador de GraphQL?

Se você já colou um pedaço de SDL GraphQL que voltou em uma linha só e tentou ler, conhece o problema. Tipos, campos, argumentos, diretivas e membros de union se grudam todos juntos e a estrutura some. Essa ferramenta resolve isso. Cole seu schema no painel da esquerda e o painel da direita renderiza com indentação de dois espaços, um campo por linha, argumentos inline e descrições em block-string mantidas acima do tipo ou campo que documentam.

O formatador é caseiro — nenhum pacote npm graphql é carregado na página, então o primeiro paint continua leve. Ele tokeniza o SDL, percorre a estrutura de chaves e emite de novo com espaçamento consistente segundo a spec GraphQL de outubro de 2021. Cobre toda construção SDL que aparece no mundo real: type, interface, union, enum, input, scalar, extend, schema, modificadores de lista e non-null ([Foo!]!), valores default, diretivas e descrições com aspas triplas. Entrada já formatada volta igualzinho.

Tudo roda no seu navegador. Sem upload, sem schema guardado em lugar nenhum. Cole, leia, copie.

Como usar o Visualizador de GraphQL

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

Cole, faça upload ou carregue um exemplo

Cole um schema GraphQL no painel Entrada à esquerda. Clique em Enviar para um arquivo .graphql, .graphqls ou .gql, ou em Exemplo para carregar um schema realista de e-commerce. Exemplo rápido de como fica um SDL minificado:

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

Schemas no estilo servidor (com extend type Query) e definições de tipos isoladas funcionam. Os formatos aceitos batem com o que ferramentas como Apollo Server processam.

Leia a saída formatada

O painel Saída à direita renderiza o SDL parseado com indentação de dois espaços. Cada campo, valor de enum e membro de union ganha sua própria linha. Argumentos ficam inline na linha do campo, então as assinaturas se leem naturalmente. Descrições escritas como block-strings ("""...""") ficam acima do tipo ou campo que descrevem, que é como a especificação GraphQL do Relay recomenda documentar um schema. Se o SDL tiver chaves desbalanceadas ou outros erros de parse, o visualizador mostra uma mensagem amigável em vez de quebrar.

Copie ou baixe

Aperte Copiar para levar o schema formatado para um pull request, doc ou chat. Aperte Baixar para salvar como .graphql. O botão de limpar do painel de entrada te devolve para o estado em branco. O parsing acontece todo no cliente — seu schema não sai da página.

Quando você de fato vai usar isso

Reviews de pull request de schema

Está revisando um PR de schema e o diff está difícil de ler porque o arquivo passou por um gerador de código que tirou a formatação? Cole a versão nova aqui, dê uma passada de olho na estrutura, depois volte para o diff com um modelo mental mais claro do que mudou. Especialmente útil quando o time está iterando sobre o que conta como um bom design de schema.

Debug de federação e subgraphs

Debugando um gateway de federação Apollo e o supergraph composto volta como um bloco gigante? Cole o SDL mergeado, ache o tipo que está se comportando errado, veja qual subgraph contribuiu com qual campo. As diretivas de federação que aparecem na saída ficam documentadas junto com o resto da sintaxe do schema.

Documentando uma API

Escrevendo doc pública para uma API GraphQL que o seu time mantém? Joga o schema no visualizador, copia a versão formatada para o wiki ou README. A forma de árvore dos tipos, interfaces e unions se lê naturalmente quando está disposta com um campo por linha.

Onboarding de novos engenheiros

Um novo colega de time está tentando aprender o formato da sua API GraphQL. Um schema formatado com as descrições visíveis acima de cada tipo é um ponto de partida bem mais amigável que o bloco sem formatação saído do codegen.

Perguntas frequentes

Ele valida meu schema ou só formata?

Só formata. O visualizador checa o balanço de chaves e aspas o suficiente para formatar, mas não verifica se o Query existe, se os tipos referenciados estão definidos ou se os argumentos das diretivas batem com a definição. Para validação completa, use a implementação de referência graphql-js ou passe pelos checks de startup do seu servidor.

Meu schema é enviado para algum servidor?

Não. O formatador roda inteiro no seu navegador. Nada é enviado, nada é logado. Pode colar schemas internos ou não publicados sem medo.

Ele lida com descrições em block-string?

Sim. Descrições com aspas triplas ("""Um pedido feito por um cliente.""") são preservadas e emitidas na linha acima do tipo ou campo que documentam. Essa é a forma canônica de escrever doc SDL segundo a spec do GraphQL.

E diretivas e scalars customizados?

Os dois são preservados. @deprecated, @key e qualquer diretiva customizada ficam inline no campo. Scalars customizados como scalar DateTime saem na própria linha. O visualizador não tenta interpretar a semântica das diretivas — isso é com o seu servidor.

SDL já formatado vai ser reformatado?

É idempotente — formatar SDL já formatado produz a mesma saída. Então dá para rodar o visualizador num check de CI ou num fluxo de colar-e-comparar sem se preocupar com mudança de espaços em branco.

Que tamanho de schema dá para colar?

Qualquer coisa que o seu navegador consiga renderizar confortavelmente. Schemas de algumas centenas de tipos não são problema. Acima de 5 MB o próprio editor Ace começa a ficar lento — o gargalo é ele, não o parser.

Outras ferramentas GraphQL

Visualizar é só uma parte do trabalho com GraphQL. Estas ferramentas cuidam do resto: