GraphQL API — это мощно, но как его документировать, чтобы разработчики остались довольны? В этой статье — готовый план действий. Мы начнём со сравнения GraphQL и REST, затем покажем, как с помощью комментариев и примеров кода превратить схему в наглядное руководство. Вы узнаете, как улучшить GraphiQL Playground подсветкой синтаксиса и создать статический справочник, если Playground недоступен. В конце вас ждёт учебный репозиторий для тренировок на реальном API.

Привет, Хабр.

Знаю, что здесь куча обзоров на различные курсы от разных школ, платформ и иже с ними. Но все-таки хочу вставить и свои 5 копеек. Рассказываю о своих ощущениях от курса «Системный аналитик», который я (успешно) окончил в августе 2024 года.

Почему я вообще в это все ввязался?

В статье расскажу про Foliant и про возможности по документированию HTTP API с его использованием. Упор сделаю на API, которые описываются с помощью OpenAPI/Swagger. Также вскользь коснусь возможностей по документированию API, описанных с помощью других спецификаций.