Документация, которую Вы сейчас читаете, является в большей степени обзорной (концептуальной), т.е. описывает общие идеи и некоторые сценарии взаимодействия, а не все рычаги взаимодействия.

Однако для использования api нужна и техническая документация на все конечные точки (URL ресурсов) и допустимые *действия с ними * (методы http GET, POST, PUT, DELETE).

API автоматически генерирует такую документацию в формате OpenAPI и предоставляет интерактивное приложение Swagger UI для работы с ней по адресу /docs.

По адресу /docs генерируется документация с русскоязычными полями биографии.

Существует возможность получить в ответах API англоязычные поля. Для этого к запросу нужно добавить параметр eng со значением true, 1, on, yes либо вовсе без значения (/public/dela/123?eng).

Документация с англоязычными полями биографии доступна по адресу /docs_en, а соответствующая OpenAPI схема для генерации классов в исползуемом Вами языке программирования доступна по адресу /openapi_en.json.

ℹ️ Не забывайте, что для получения англоязычных полей параметр eng нужно задавать явно даже в SwaggerUI по адресу /docs_en, иначе Вы получите русскоязычные поля в выдаче.

Страница Swagger UI состоит из двух блоков:

1. описание допустимых запросов Для каждой пары "URL ресурса" и "метод" описывается:
   • набор передаваемых параметров, их обязательность и значения по умолчанию
   • пример json тела запроса (для POST и PUT)
   • коды http ответов и примеры возвращаемых json.

---

2. схемы использующихся в первом блоке JSON объектов (в том числе вложенных)
   • имя поля
   • признак обязательности
   • тип данных - если задан вложенный объект, то можно тут же развернуть его схему.

В дальнейшем мы сфокусируемся только на первой части.

Допустимые запросы распределены по следующим основным:

• auth - авторизация
• editor - биографии для редактирования
• public - полные биографии
• files - файлы

Помимо просмотра, Swagger UI позволяет отправлять запросы в api.

Для работы нам нужно сначала авторизоваться

В верхнем правом углу страницы есть зелёная кнопка . Нужно нажать на неё и в появившемся окне ввести свой логин и пароль в первые два поля, далее нажать кнопку Authorize внизу.

После успешной авторизации картинка будет такой:

⚠️ После успешной авторизации Swagger UI запоминает токен доступа и передаёт его с каждым запросом. Время действия токена доступа - один час. После этого нужно сново нажать в верхнем правом углу кнопку , в появившемся окне Logout. Затем надо снова залогиниться.

Подробнее про авторизацию см здесь

Проверим свои учётные данные.

• В разделе auth раскроем конечную точку /whoami
• Нажимаем кнопку "Try it out" справа для перехода в режим отправки запросов в api.
• Нажимаем большую синюю кнопку Execute
• Видим ответ - мы пользователь reader и обладаем ролью reader.

• В разделе public открываем /public/dela, нажимаем Try it out
• в качестве парамера text_filter указываем "Тутаев"
• выполняем запрос
• В результате получаем упорядоченный по релевантности список из первых 20 биографий, в которых упоминается слово "Тутаев"

Swagger UI является таким же клиентом api, как и любой другой, так что если Вам не удаётся правильно отправить в api запрос, можно подсмотреть, как это делает он одним из следующих способов:

1. Если Вы знакомы с утилитой curl, то Swagger UI показывает синтаксис отправки запроса прямо в интерфейсе
2. Можно открыть консоль запросов браузера и посмотреть, что отправляет Swagger.