Если открыть GraphQL API в Apollo Studio, мы увидим документацию по методам. Посмотрим на примере системы Cards, ссылка в Apollo — https://cards.bugred.ru/online.
Чтобы документация появилась, нужно вызвать первый запрос с авторизацией — система защищена, без заголовка Authorization ничего не вернет (пароль см в документации по ссылке выше). Можно послать универсальный запрос: query UniversalQuery { __typename}
И вот мы видим, какие вообще методы нам доступны. Посмотрим на запросы Query:
Зайдем в любой метод, например, в метод getUser. И смотрите, у возвращаемого объекта есть описание на русском! «Тип данных пользователь»:
А если провалиться в любое поле (блок Fields), например, в age, мы увидим, что это «возраст пользователя»:
Откуда берется эта документация? Из схемы!
В схеме GraphQL можно писать документацию через тройные кавычки """. И некоторые системы, типа Apollo, могут её считывать и красиво показывать вам.
Пойдем посмотрим на схему Cards. Для этого нужно в левом верхнем углу выбрать значок молекулы, а потом перейти в SDL — это schema definition language, схема в «чистом» виде.
И там мы как раз видим описание для типа данных User — «Тип данных пользователь», а для его поля age — «возраст пользователя»:
Соответственно, везде, где в ответе возвращается User, будут такие подсказки. Удобно!
Посмотрим в SDL на описание самого запроса getUser (можно найти его через ctrl + f):
Ах вот оно что! Так это странное «пояснение», которое мы видели ранее, «a query» — это описание этого метода!
И если бы разработчик написал нормальное описание (ну хотя бы то, что было в документации, я ведь давала ему такую схему), оно бы отображалось в самом запросе. Соответственно, зашел в запрос — почитал документацию. Очень удобно!
Поэтому при описании схемы не пренебрегайте описание методов, объектов и их полей через тройные кавычки — ведь по ним строится очень удобная в использовании документация!
PS — статья написана в помощь студентам моего курса по GraphQL.
Комментариев нет:
Отправить комментарий