Indata

Utdata

Vad är GraphQL-visaren?

Om du någonsin har klistrat in en bit GraphQL SDL som kom tillbaka på en enda rad och försökt läsa det vet du problemet. Typer, fält, argument, direktiv och unionsmedlemmar klumpar ihop sig och strukturen försvinner. Det här verktyget fixar det. Klistra in ditt schema i vänsterpanelen och högerpanelen renderar det med två-stegs indrag, ett fält per rad, argument inline och block-string-beskrivningar ovanför den typ eller fält de dokumenterar.

Pretty-printern är handskriven — inget graphql npm-paket laddas in på sidan, så första rendering förblir liten. Den tokeniserar SDL:n, vandrar genom klammerstrukturen och skriver ut den igen med konsekvent spacing enligt GraphQL-specen från oktober 2021. Den klarar varje SDL-konstruktion man stöter på i praktiken: type, interface, union, enum, input, scalar, extend, schema, list- och non-null-modifierare ([Foo!]!), defaultvärden, direktiv och beskrivningar med trippelcitattecken. Redan välformaterad indata kommer tillbaka oförändrad.

Allt körs i din webbläsare. Ingen uppladdning, inget schema lagrat någonstans. Klistra in, läs, kopiera.

Så använder du GraphQL-visaren

Tre snabba steg. Knapparna som beskrivs nedan är de faktiska knapparna på den här sidan.

Klistra in, ladda upp eller ladda ett exempel

Klistra in ett GraphQL-schema i den vänstra Indata-panelen. Klicka Ladda upp för en .graphql-, .graphqls- eller .gql-fil, eller tryck Exempel för att ladda ett realistiskt e-handels-schema. Snabbt exempel på hur minifierad SDL ser ut:

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

Både scheman i serverstil (med extend type Query) och fristående typdefinitioner fungerar. De accepterade formerna matchar det som verktyg som Apollo Server parsar.

Läs den formaterade utdatan

Den högra Utdata-panelen renderar den parsade SDL:n med två-stegs indrag. Varje fält, enum-värde och unionsmedlem får sin egen rad. Argument förblir inline på fältraden, så signaturer läses naturligt. Beskrivningar skrivna som block-strings ("""...""") hamnar ovanför den typ eller fält de beskriver, vilket är sättet som Relays GraphQL-specifikation rekommenderar för att dokumentera ett schema. Om SDL:n har obalanserade klammer eller andra parse-fel visar visaren ett vänligt meddelande istället för att krascha.

Kopiera eller ladda ner

Tryck Kopiera för att ta med det formaterade schemat till en pull request, doc eller chatt. Tryck Ladda ner för att spara som .graphql. Rensa-knappen på indatapanelen återställer dig till tomt läge. Parsningen sker helt på klientsidan — ditt schema lämnar aldrig sidan.

När du faktiskt kommer använda det här

Granskningar av schema-pull-requests

Granskar en schema-PR och diffen är svår att läsa eftersom filen körts genom en kodgenerator som tagit bort formateringen? Klistra in den nya versionen här, skanna strukturen med ögonen, och gå sedan tillbaka till diffen med en tydligare mental modell av vad som ändrats. Särskilt användbart när teamet itererar på vad som räknas som bra schemadesign.

Federations- och subgraf-debugging

Debuggar en Apollo federation-gateway och det sammansatta supergraf-schemat kommer tillbaka som ett enda gigantiskt block? Klistra in den mergade SDL:n, hitta typen som beter sig konstigt, se vilken subgraf som bidrog med vilket fält. Federation-direktiven som dyker upp i utdatan dokumenteras tillsammans med resten av schemasyntaxen.

Dokumentera ett API

Skriver publik dokumentation för ett GraphQL-API som ditt team äger? Släpp schemat i visaren, kopiera den formaterade versionen till wikin eller READMEn. Trädformen av typer, interfaces och unioner läses naturligt när den är upplagd med ett fält per rad.

Onboarding av nya ingenjörer

En ny lagkamrat försöker lära sig formen på ert GraphQL-API. Ett formaterat schema med beskrivningar synliga ovanför varje typ är en mycket vänligare startpunkt än det oformaterade blocket från codegen-utdatan.

Vanliga frågor

Validerar det mitt schema, eller bara formaterar det?

Bara formaterar. Visaren kollar klammer- och citattecknebalans tillräckligt för att kunna pretty-printa, men verifierar inte att Query finns, att refererade typer är definierade, eller att direktivargument matchar sina definitioner. För full validering, använd referensimplementationen graphql-js eller kör det genom serverns startup-checks.

Skickas mitt schema till en server?

Nej. Pretty-printern körs helt i din webbläsare. Inget laddas upp, inget loggas. Säkert att klistra in interna eller opublicerade scheman.

Hanterar det block-string-beskrivningar?

Ja. Beskrivningar med trippelcitattecken ("""En beställning gjord av en kund.""") bevaras och skrivs ut på raden ovanför den typ eller fält de dokumenterar. Det här är det kanoniska sättet att skriva SDL-dokumentation enligt GraphQL-specen.

Och direktiv och custom scalars?

Båda behålls. @deprecated, @key och alla custom direktiv stannar inline på fältet. Custom scalars som scalar DateTime skrivs ut på sin egen rad. Visaren försöker inte tolka direktivsemantik — det är upp till din server.

Kommer redan formaterad SDL att om-formateras?

Det är idempotent — att pretty-printa redan välformaterad SDL ger samma output. Så du kan köra visaren i en CI-check eller i ett klistra-och-jämför-workflow utan att oroa dig för whitespace-drift.

Hur stort schema kan jag klistra in?

Allt din webbläsare renderar bekvämt. Scheman med några hundra typer är inga problem. Över 5 MB börjar Ace-editorn själv bli långsam — det är flaskhalsen, inte parsern.

Andra GraphQL-verktyg

Att visa är en del av jobbet med GraphQL. De här verktygen tar hand om resten: