← Все гайды

Визуализация GraphQL-схемы онлайн: карта типов как в GraphQL Voyager

· 3 мин чтения

GraphQL

Как построить карту GraphQL-схемы: выбор корня Query, Mutation или Subscription, подсветка связей, перетаскивание карточек, свёртка Relay, выгрузка в SVG и PNG.

Большую GraphQL-схему трудно охватить по тексту: десятки типов ссылаются друг на друга, интерфейсы и объединения прячут конкретные типы. Карта схемы показывает её графом — как GraphQL Voyager, но прямо рядом с кодом: карточки типов с полями и стрелки от каждого поля к типу его значения.

Как построить карту

  1. Откройте песочницу GraphQL и вставьте схему в SDL или JSON-ответ introspection — карта построится справа автоматически.
  2. В панели «Описание» выберите Корень: Query, Mutation, Subscription или Все типы. На карте остаются типы, достижимые от корня по полям; корень — слева.
  3. Щёлкните по типу — его связи подсветятся, остальное приглушится, а в панели откроется описание. Щелчок по полю подсвечивает связь этого поля.
  4. Перетащите карточки мышью, чтобы расположить схему удобнее: стрелки перестроятся сами. Расположение сохраняется вместе со схемой.
Карта схемы Star Wars: интерфейс Character перенесён под корень Query, его связи подсвечены
Интерфейс Character перенесён вручную и выбран: подсвечены поля, которые его возвращают, и его реализации

Как читать карту

  • Карточка типа — заголовок с именем и видом (type, interface, union), строки полей «имя: Тип». Многоточие (…) после имени — у поля есть аргументы, они видны во всплывающей подсказке и в панели «Описание».
  • Сплошная стрелка — поле ссылается на тип; пунктирная — тип реализует интерфейс; точечная — тип входит в объединение.
  • Зачёркнутое поле — устаревшее (@deprecated), причина — в подсказке.
  • Скаляры, перечисления и входные типы отдельными карточками не показываются: они видны в строках полей и в панели «Описание».

Настройка карты

  • Поля скалярных типов и enum — снимите галочку, чтобы оставить на карточках только связи между типами.
  • Свернуть Relay — обёртки Connection, Edge и PageInfo сворачиваются в списки с пометкой Relay; снимите галочку, чтобы увидеть их.
  • Скрыть устаревшие поля и По алфавиту — меньше шума и привычный порядок полей.
  • Кнопки в углу карты: масштаб + и − (или колесо мыши), ⤢ — вписать в экран, ⊞ — расставить карточки автоматически и забыть ручное расположение.

Картинка для документации

Файл → Скачать → Схема SVG или Схема PNG — карта в текущем расположении карточек. Чтобы карта жила в базе знаний и обновлялась вместе со схемой, поделитесь схемой по ссылке и вставьте её виджетом «Помощника SA» в Confluence или MediaWiki.

Что ещё

Вопросы и ответы

Почему на карте нет некоторых типов? Карта строится от выбранного корня: тип, недостижимый от него по полям, не показывается — в списке панели «Описание» он отмечен кружком. Выберите корень «Все типы».

Сохранится ли ручное расположение после правки схемы? Да: передвинутые карточки остаются на местах, новые типы раскладываются автоматически. Расположение хранится в документе и в версиях истории; кнопка ⊞ возвращает автоматическую раскладку.

Можно ли двигать карточки в схеме, открытой по ссылке? Нет, просмотр по ссылке — только чтение. Откройте копию в своей песочнице.