← Все гайды

Introspection в SDL: схема GraphQL из JSON-ответа __schema

· 2 мин чтения

GraphQL

Как получить читаемую схему GraphQL на SDL из результата introspection существующего API, посмотреть её карту и выгрузить обратно в JSON для генераторов кода.

У работающего GraphQL API схема обычно есть только «внутри» сервера, а снаружи её можно получить запросом introspection — JSON-ответом {"data": {"__schema": …}}. Читать такой JSON неудобно. Редактор GraphQL «Помощника SA» принимает его как есть: показывает карту типов и выгружает схему в привычном SDL.

Как получить SDL из introspection

  1. Получите ответ introspection: в GraphiQL, Apollo Sandbox, Postman или Insomnia выполните запрос introspection (обычно кнопка «Schema» → «Download JSON» или «Export»), либо отправьте стандартный запрос IntrospectionQuery сами.
  2. Откройте песочницу GraphQL и вставьте JSON вместо примера или откройте файл: Файл → Открыть файл…. Рядом с названием документа появится пометка INTROSPECTION.
  3. Справа построится карта типов — так же, как для SDL.
  4. Выберите Файл → Скачать → GraphQL SDL (.graphql) — скачается схема на SDL с описаниями типов и полей.
JSON-ответ introspection в редакторе GraphQL и меню скачивания GraphQL SDL
Результат introspection распознан: карта построена, схему можно скачать в SDL

Запрос introspection

Если инструмента под рукой нет, отправьте на адрес API POST-запрос с телом {"query": "…"}, где запрос — стандартный IntrospectionQuery. Его сокращённое начало:

query IntrospectionQuery {
  __schema {
    queryType { name }
    mutationType { name }
    subscriptionType { name }
    types { ...FullType }
    directives { name description locations args { ...InputValue } }
  }
}

Полный текст запроса (с фрагментами FullType, InputValue и TypeRef) есть в библиотеке graphql-js — функция getIntrospectionQuery(). Как устроена интроспекция, — в разделе документации «Интроспекция».

И обратно: SDL в introspection

Для схемы на SDL пункт Файл → Скачать → Результат introspection (.json) выгружает её в формате ответа introspection — такой файл принимают генераторы кода клиентов и инструменты вроде GraphQL Voyager.

Что ещё

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

Сервер отвечает ошибкой на запрос introspection. Во многих боевых API интроспекция отключена ради безопасности. Попросите схему у команды API или выполните запрос на тестовом стенде.

Подходит ли ответ без обёртки data? Да, редактор принимает и объект {"__schema": …} напрямую.

Сохраняются ли описания и устаревшие поля? Да: описания типов, полей и аргументов, значения по умолчанию и @deprecated с причиной переносятся в SDL. Применения своих директив к типам и полям introspection не передаёт — в SDL их не будет.