Swagger - особый инструмент, автоматически документирующий интерфейс RESTful API вашего приложения.
Его достоинство заключается в том, что он позволяет не только изучить все эндпойнты приложения, но и сразу же протестировать их в деле, отправить любой запрос и получить ответ.
Для доступа к Swagger необходимо в опубликованном приложении перейти в Preview и нажать на наименование нужного плана публикации (Deploy Plan).
Открывшееся окно содержит список доступных endpoints и методов, связанных с этими endpoints. Некоторые запросы доступны только определенным группам авторизованных пользователей (проверяется в Middleware модуля Auth для каждого конкретного запроса в разделе Endpoints). Для запросов, требующих авторизации, нужно получить Bearer Token.
Для получения токена можно обратиться к соответствующему эндпоинту прямо в Swagger (раздел Auth, запрос POST /auth).
Далее, нужно нажать Try it out и ввести логин и пароль пользователя, для авторизации и получения токена.
Нажав Execute будет отправлен запрос. В ответе запроса, если он успешен, нужно найти поле token, которое и будет содержать токен авторизованного пользователя.
Второй способ получения токена авторизованного пользователя заключается в том, что в сгенерированном приложении, отправив запрос и получив ответ на него, можно найти токен в теле самого запроса. Для этого:
- Откройте инструмент разработчика в браузере (F12 в Google Chrome).
- Отправьте запрос на сервер (например, обновив данные таблицы). Запрос должен быть отправлен авторизованным пользователем, у которого есть доступ к endpoint.
- Открыть Network и выбрать соответствующий запрос.
- Во вкладке 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 году.
