Klíčové poznatky
- 01Formátuje dotazy, mutace, předplatné a SDL schémata pomocí oficiálního graphql.js parseru.
- 02Validuje syntaxi a hlásí přesný řádek a sloupec chyb — bez schématu.
- 03GraphQL komentáře (#) jsou odstraňovány při formátování; pro dokumentaci, kterou chcete zachovat, použijte description stringy.
- 04Běží zcela v prohlížeči — vnitřní API dotazy a proprietární schémata zůstávají soukromá.
Proč formátovat GraphQL dokumenty?
GraphQL dotazy se mohou stát složitými rychle — vnořené fragmenty, vložené proměnné, více definic operací a SDL definic typů s interface a direktivy. Konzistentní formátování dělá peer review rychlejší a usnadňuje vidět chybějící zavírací složené závorky nebo neshody argumentů na první pohled.
Formáter používá referenční graphql.js parser — stejný parser, který se dodává s GraphQL specifikací. To znamená, že kanonické formátování, které zde dostanete, odpovídá tomu, co vytvoří Prettier GraphQL plugin a nejvíc GraphQL nástrojů. Cokoliv, co se parsuje čistě zde, se parsuje čistě v Apollo, Relay a graphql-request.
Jak formátovat GraphQL dokument
- 01
Vložte svůj GraphQL
Vložte dotaz, mutaci, předplatné, fragment, či SDL schéma definici do panelu vstupů.
- 02
Klikněte na Formátovat
Parser posílá dokument s kanonickým odsazením — dvou-mezerovým odsazením, jedním polem na řádek, konzistentním zarovnáním argumentů. Výsledek se zobrazí v panelu výstupu.
- 03
Volitelně validujte
Klikněte na Validate pro potvrzení, že se dokument parsuje bez vytváření formátovaného výstupu. Výsledek je potvrzení či seznam chyb syntaxe s čísly řádky a sloupce.
- 04
Zkopírujte výsledek
Klikněte na Copy pro grabnutí formátovaného dokumentu. Vložte do svého kódsusu, PR popisu, či dokumentačního souboru.
Bezpečné pro vnitřní schémata a API dotazy
Parser graphql.js běží zcela v prohlížeči. Žádný text operace či definice schématu se neposílá do serveru. To z něj dělá bezpečné formátování dotazů, které odkazují na soukromé názvy polí či interní typové systémy, které nechcete odhalit nástrojům třetích stran.
Validace zde je pouze syntaktická — nástroj kontroluje, že dokument je platný GraphQL dokument, ale nekontroluje, zda názvy polí existují v reálném schématu, zda proměnné odpovídají typům argumentů, či zda jsou direktivy správně aplikovány. Validace vědomí schématu vyžaduje, aby cílové schéma bylo načteno vedle dokumentu.
Časté otázky k GraphQL Formáteru
Validuje formátování GraphQL proti schématu?
Ne — pouze syntaxe validace. Kontrola, zda pole a argumenty existují, vyžaduje cílové schéma. Tento nástroj potvrzuje, že dokument je platný GraphQL dokument, nic víc.
Budou komentáře v mém GraphQL zachovány?
Ne. Řádky začínající # jsou odstraněny parserem. Pro dokumentaci, která by měla přežít formátování, použijte trojité citované description stringy.
Která verze GraphQL spec je podporována?
Říjnová 2021 specifikace, včetně OneOf input objektů a @specifiedBy direktivy.
Mohu formátovat SDL schéma definice, ne pouze dokumenty operací?
Ano. Definice typů, prohlášení interface, union typy, enums, direktivy a popisy všechny správně round-trip formátorem.
Je dotaz či schéma nahrány kdekoli?
Ne. Parser graphql.js běží zcela v prohlížeči — nic neopisuje vaše zařízení.