8.5. Swagger UI

Swagger - это фреймворк для спецификации REST API. Он дает возможность не только интерактивно просматривать спецификацию, но и отправлять запросы. В swagger можно
использовать весь функционал API который присутствует на сервере WICO. Все методы имеют описание, зачем нужен, что значат поля на входе и в ответах.

Swagger доступен по ссылке вида http://dev.wico.pro:8080/swagger-ui/index.html#/ где dev.wico.pro:8080 адрес контроллера. Для работы в swagger требуется bearer авторизация. Токен можно получить в

JWT Authentication в методе POST /api/authenticate. Для начала работы надо нажать в правом верхнем углу кнопку Try it out.

После нажатия кнопки становится доступно для редактирования окно с параметрами для запроса.

Там следует ввести username и password с которыми вы зарегистрированы в контроллере. И нажать ниже кнопку Execute.

Пример запроса на curl для получения токена.

curl -X 'POST' \
  'http://dev.wico.pro:8080/api/authenticate' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "username",
  "password": "password"
}'

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

Копируем токен. Находим в самом верху сваггера кнопку Authorize и нажимаем.

В открывшееся поле вставляем токен и нажимаем  Authorize, закрываем окно ввода токена. Теперь можно пользоваться любыми методами если у вас есть на это достаточно прав  в контроллере ( Некоторые методы доступны только с ролью ADMIN). 
Токен будет автоматически подставлен в шапку запроса.

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

Нажимаем Execute.

Ответ:

Запрос на curl:

curl -X 'GET' \
  'http://dev.wico.pro:8080/api/v1/devices/44%3AD1%3AFA%3AE0%3A9D%3A40/traffic?interval=Day' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTcxNTYyOTYxNSwiaWF0IjoxNzE1NjExNjE1fQ.zxfL7kt5gsuRRwt7UW5Ozfjk-Lc69JLZGWLVdgnsmM011o4VW-CrMM9PNxa0A3pxoMCrQcaM-uEmWxRJhvjwJw'

Ответ в формате json:

{
  "unit": "HOURS",
  "results": [
    {
      "label": null,
      "dateTime": {
        "year": 0,
        "month": 0,
        "week": null,
        "day": null,
        "hour": null,
        "minute": null,
        "period": null
      },
      "startDate": "2024-05-12T15:45:29.663Z",
      "endDate": null,
      "missed": false,
      "createdAt": "2024-05-12T15:46:00.000+00:00",
      "speedTx": 205328,
      "speedRx": 6559664,
      "rssi": 0,
      "trafficIn": 0.21,
      "trafficOut": 6.56
    },
    {
      "label": null,
      "dateTime": {
        "year": 0,
        "month": 0,
        "week": null,
        "day": null,
        "hour": null,
        "minute": null,
        "period": null
      },
      "startDate": "2024-05-12T16:45:29.663Z",
      "endDate": null,
      "missed": false,
      "createdAt": "2024-05-12T16:46:00.000+00:00",
      "speedTx": 56064,
      "speedRx": 12072,
      "rssi": 0,
      "trafficIn": 0.06,
      "trafficOut": 0.01
    },...

]

Для выполнения POST  запроса, если требуется что-либо загрузить, изменить какие то настройки, или что-то сохранить заполняем тело запроса. Например создание нового пользователя.

В ответе получаем id нового пользователя.

Тот же запрос на curl:

curl -X 'POST' \
  'http://dev.wico.pro:8080/api/v1/users' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTcxNTYyOTYxNSwiaWF0IjoxNzE1NjExNjE1fQ.zxfL7kt5gsuRRwt7UW5Ozfjk-Lc69JLZGWLVdgnsmM011o4VW-CrMM9PNxa0A3pxoMCrQcaM-uEmWxRJhvjwJw' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": null,
  "username": "test_user",
  "password": "Test_user1",
  "role": "OPERATOR",
  "fullname": "Василий Пупкин",
  "company": "Netams",
  "email": "pupkin@mail.ru",
  "phone": "9229229191",
  "telegramId": "",
  "enabled": true,
  "lastLogin": "2024-05-13T07:05:26.941Z",
  "groupIdsStr": "",
  "createdAt": "2024-05-13T07:05:26.941Z",
  "updatedAt": "2024-05-13T07:05:26.941Z",
  "passwordHistoryList": "",
  "passwordHistory": [
    "string"
  ],
  "lastPasswordSetDate": 0,
  "changePasswordRequested": true,
  "passwordNeverExpires": true,
  "showHelpTooltips": true,
  "locale": "",
  "name": "",
  "groupIds": [
    "0"
  ]
}'

Ответ:

{"data":{"id":"test_user"}}

Удаление пользователя:

Ответ:

На curl :

curl -X 'DELETE' \
  'http://dev.wico.pro:8080/api/v1/users/test_user' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTcxNTYyOTYxNSwiaWF0IjoxNzE1NjExNjE1fQ.zxfL7kt5gsuRRwt7UW5Ozfjk-Lc69JLZGWLVdgnsmM011o4VW-CrMM9PNxa0A3pxoMCrQcaM-uEmWxRJhvjwJw'

Краткая информация о доступном API представлена ниже, более подробное описание а так же описание работы всех методов можно получить в swagger.