0:00
[БЕЗ_ЗВУКА] В этом видео мы поговорим про SWAGGER.
SWAGGER — это набор утилит для Open API Specification,
которая раньше называлась SWAGGER Specification.
Это спецификация для описания вашего API, которая позволяет на основе
этого описания генерировать документацию, клиентский код, серверный код,
тестирование и проектировать само API в удобном инструменте.
Давайте посмотрим, что из себя представляет это формат.
Итак, вот Json с этим форматом SWAGGER,
что версия 2.0, какая-то информация,
в данном случае title был сгенерирован из session.proto, какой формат он принимает,
какой формат он возвращает, какие сами API он предоставляет,
в данном случае v1/session/check/{ID}, какие ответы он отдает,
какие параметры он принимает и структура данных, которую он возвращает.
Конечно, в Json смотреть это не очень удобно, и скорее всего, вы уже запутались,
поэтому давайте посмотрим, как выглядит документация.
У SWAGGER есть команда serve для генерирования документации.
Я указываю формат, файл, в котором описано мое API,
на 8082 порту, запускаем, и вот мы видим уже красивую документацию.
Вот мой сервис AuthChecker, вот его метод Check,
какие у него есть параметры, какой формат он возвращает,
как можно из него что-то получить, create и delete.
Соответственно, если у вас большой набор микросервисов,
очень много методов у них, то иметь хорошую документацию — это уже благо.
Теперь давайте посмотрим дальше,
каким образом можно сгенерировать клиент до вашего API, используя этот формат.
Итак, есть следующая команда.
swagger generate, я говорю, что client, указываю,
из какого файл мне всё это генерировать,
назову это session client и положу в папку session client.
Запустим, он немножко подумает,
потом сгенерирует нам огромное количество файлов.
Итак, вот session client, он мне сюда сгенерировал
непосредственно сам клиент, auth_checker,
это мой сервис уже auth_checker, и модели для всего этого добра.
Давайте посмотрим, каким образом теперь при помощи этого сгенерированного
клиента обратиться к моему сервису.
У меня есть код consumer, я подключаю довольно много разных инклюдов,
создаю транспорт, где указываю, на какой адрес мне идти,
создаю клиента, создаю мой непосредственно менеджер сессий,
потому что у меня внутри одного API может быть несколько подсервисов.
Теперь вызываю session manager.Create, вызываю NewCreateParams().WithBody.
Почему WithBody?
Откуда это Body взялось?
Потому что это постпараметры.
Указываю, что я хочу CreateSession.
Запускаем.
session ID получили.
Теперь я могу проверить по этой сессии, что там внутри лежит,
удалить и проверить еще раз.
Давайте запустим.
Итак, запускаем consumer.
Отмечу, что поскольку мой код сгенерирован на
основе swagger описания, то сейчас он идет в ту Reverse Proxy в grpc-gateway,
которая потом уже входит в grpc-сервис.
То есть у меня получается http клиент к http серверу,
который уже является grpc-клиентом grpc-сервису.
Смотрите, у меня уже три появилось сервиса.
Конечно, при помощи swagger можно сгенерировать и серверное описание.
Это будет очень забавно.
Мы сначала сгенерировали grpc-сервис, потом через несколько
итераций он уже генерируется опять сервер из swagger.
Swagger — это очень хороший инструмент,
если у вас в работе используется очень много микросервисов, он позволяет как-то
их стандартизировать и добиться контроля над форматом их ответов.
Штука это очень мощная с миллионом параметров,
с миллионом опций, и действительно стоит более детального изучения.
Романов Василий ВячеславовичSoftware engineer
