Что такое Swagger и как его использовать

Swagger - особый инструмент, автоматически документирующий интерфейс RESTful API вашего приложения.

Его достоинство заключается в том, что он позволяет не только изучить все эндпойнты приложения, но и сразу же протестировать их в деле, отправить любой запрос и получить ответ.

Для доступа к Swagger необходимо в опубликованном приложении перейти в Preview и нажать на наименование нужного плана публикации ( Deploy Plan).

Открывшееся окно содержит список доступных endpoints и методов, связанных с этими endpoints. Некоторые запросы доступны только определенным группам авторизованных пользователей (проверяется в Middleware модуля Auth для каждого конкретного запроса в разделе Endpoints). Для запросов, требующих авторизации, нужно получить Bearer Token.

Для получения токена можно обратиться к соответствующему эндпоинту прямо в Swagger (раздел Auth, запрос POST /auth).

Далее, нужно нажать Try it out и ввести логин и пароль пользователя, для авторизации и получения токена.

Нажав Execute будет отправлен запрос. В ответе запроса, если он успешен, нужно найти поле token, которое и будет содержать токен авторизованного пользователя.

Второй способ получения токена авторизованного пользователя заключается в том, что в сгенерированном приложении, отправив запрос и получив ответ на него, можно найти токен в теле самого запроса. Для этого:

1. Откройте инструмент разработчика в браузере (F12 в Google Chrome).
2. Отправьте запрос на сервер (например, обновив данные таблицы). Запрос должен быть отправлен авторизованным пользователем, у которого есть доступ к endpoint.
3. Открыть Network и выбрать соответствующий запрос.
4. Во вкладке Headers найти раздел Request Headers и в заголовке Authorization получить необходимый токен.

Передать токен в Swagger можно, нажав на Authorize и вставив скопированный токен.

Далее можно приступать к тестированию запросов. Для этого необходимо выбрать нужную группу и метод в ней. Нажав Try it out и заполнив входные параметры запроса, нажмите Execute, чтобы выполнить запрос.

Самый ожидаемый ответ, в случае правильной обработки запроса сервером, имеет код 200 и показывает то, как должна выглядеть структура ответа.

Остальные коды показаны скорее для некоторого ориентира на стандарт и применимы для автосгенерированных запросов.

• 401 - запрос не был выполнен успешно, так как необходимый токен авторизации отсутствует или не верен.

  

• 404 - запрос был обработан успешно, но искомый ресурс не найден.

  

• 422 - были переданы неправильные параметры на вход запроса.

  

• 500 - ошибка обработки запроса сервером.

  

Получение кастомных ошибок

Для кастомных БП и связанных с ними запросов возможно создавать свои коды ошибок с описанием с помощью блока Raise Error в редакторе БП. Пример такого БП ниже:

В этом случае, при неудачной попытке запроса к эндпоинту, связанному с БП выше, сервер выдаст ошибку 418, содержащую текст ошибки при выполнении блока DB: Create Candidate. Код ошибки в данном примере может любой, который задаст пользователь.

Примечание: HTTP код ошибки 418 I'm a teapot сообщает о том, что сервер не может приготовить кофе, потому что он чайник. Эта ошибка ссылается на Hyper Text Coffee Pot Control Protocol (гипертекстовый протокол кофейников) который был первоапрельской шуткой в 1998 году.