71

internal/http/auth.go

@@ -26,6 +26,17 @@ import (
 //           LOGIN USER
 // ------------------------------
 
+// @Summary Вход пользователя
+// @Description Аутентификация пользователя по email и паролю
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param request body rmodel.LoginUserRequest true "Данные для входа"
+// @Success 200 {object} rmodel.LoginUserResponse "Успешная аутентификация"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неверные учетные данные"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/login [post]
 func (h *handler) loginHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "loginHandler"
 
@@ -110,6 +121,17 @@ func (h *handler) loginHandler(w http.ResponseWriter, r *http.Request) {
 //         REGISTER USER
 // ------------------------------
 
+// @Summary Регистрация пользователя
+// @Description Создание нового пользователя в системе
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param request body rmodel.UserCredentials true "Данные для регистрации"
+// @Success 201 {object} rmodel.RegisterResponse "Пользователь успешно создан"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 409 {object} map[string]string "Пользователь уже существует"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/register [post]
 func (h *handler) registerHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "registerHandler"
 
@@ -301,6 +323,17 @@ func (h *handler) saveUser(ctx context.Context, uid string, creds rmodel.UserCre
 //         LOGOUT USER
 // ------------------------------
 
+// @Summary Выход пользователя
+// @Description Завершение сессии пользователя
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param request body rmodel.LogoutUserRequest true "Токен для выхода"
+// @Success 200 "Успешный выход"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неверный токен"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/logout [post]
 func (h *handler) logoutHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "logoutHandler"
 
@@ -327,6 +360,17 @@ func (h *handler) logoutHandler(w http.ResponseWriter, r *http.Request) {
 //       REFRESH USER TOKEN
 // ------------------------------
 
+// @Summary Обновление токена доступа
+// @Description Получение нового access token по refresh token
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param request body rmodel.RefreshTokenRequest true "Refresh token"
+// @Success 200 {object} rmodel.RefreshTokenResponse "Новые токены"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неверный refresh token"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/refresh-token [post]
 func (h *handler) refreshTokenHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "refreshTokenHandler"
 
@@ -362,6 +406,17 @@ func (h *handler) refreshTokenHandler(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+// @Summary Страница подтверждения email
+// @Description HTML страница для подтверждения email адреса пользователя
+// @Tags auth
+// @Accept html
+// @Produce html
+// @Param uid query string true "ID пользователя"
+// @Param token query string true "Токен подтверждения"
+// @Success 200 {string} string "HTML страница подтверждения"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/confirm_email [get]
 func (h *handler) confirmEmailPageHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "confirmEmailPageHandler"
 
@@ -418,6 +473,16 @@ func (h *handler) confirmEmailPageHandler(w http.ResponseWriter, r *http.Request
 // 	  	  RESET PASSWORD
 // ------------------------------
 
+// @Summary Запрос восстановления пароля
+// @Description Отправка OTP кода на email для восстановления пароля
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param request body rmodel.ForgotPasswordRequest true "Данные для восстановления пароля"
+// @Success 200 {object} map[string]string "OTP код отправлен"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/forgot_password [post]
 func (h *handler) forgotPasswordHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "forgotPasswordHandler"
 
@@ -475,6 +540,17 @@ func (h *handler) forgotPasswordHandler(w http.ResponseWriter, r *http.Request)
 	w.WriteHeader(http.StatusCreated)
 }
 
+// @Summary Валидация OTP кода
+// @Description Проверка OTP кода для восстановления пароля
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param otp query string true "OTP код"
+// @Param email query string true "Email пользователя"
+// @Success 200 {object} map[string]string "OTP код валиден"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/validate_otp [get]
 func (h *handler) validateOTPHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "validateOTPHandler"
 
@@ -519,6 +595,16 @@ func (h *handler) validateOTPHandler(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+// @Summary Сброс пароля
+// @Description Установка нового пароля после валидации OTP кода
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param request body rmodel.ResetPasswordRequest true "Данные для сброса пароля"
+// @Success 200 {object} map[string]string "Пароль успешно изменен"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/reset_password [put]
 func (h *handler) resetPasswordHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "resetPasswordHandler"
 

internal/http/balance.go

@@ -12,6 +12,17 @@ import (
 	"github.com/gorilla/mux"
 )
 
+// @Summary Получить баланс агента
+// @Description Получение текущего баланса агента
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Success 200 {object} rmodel.BalanceGetResponse "Баланс агента"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/balance [get]
 func (h *handler) getBalanceAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getBalanceAgentHandler"
 
@@ -42,6 +53,17 @@ func (h *handler) getBalanceAgentHandler(w http.ResponseWriter, r *http.Request)
 	}
 }
 
+// @Summary Получить список транзакций агента
+// @Description Получение списка транзакций агента с возможностью фильтрации
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Success 200 {object} rmodel.TransactionListGetResponse "Список транзакций"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/transactions [get]
 func (h *handler) getTransactionListAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getTransactionListAgentHandler"
 
@@ -84,6 +106,18 @@ func (h *handler) getTransactionListAgentHandler(w http.ResponseWriter, r *http.
 	}
 }
 
+// @Summary Создать транзакцию агента
+// @Description Создание новой транзакции для агента
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param request body rmodel.TransactionCreateRequest true "Данные транзакции"
+// @Success 201 {object} rmodel.TransactionCreateResponse "Транзакция создана"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/transactions [post]
 func (h *handler) createTransactionAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "createTransactionAgentHandler"
 
@@ -146,6 +180,17 @@ func (h *handler) createTransactionAgentHandler(w http.ResponseWriter, r *http.R
 	}
 }
 
+// @Summary Получить список банковских счетов агента
+// @Description Получение списка банковских счетов агента
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Success 200 {object} rmodel.BankAccountListGetResponse "Список банковских счетов"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/bank_accounts [get]
 func (h *handler) getBankAccountListAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getBankAccountListAgentHandler"
 
@@ -178,6 +223,18 @@ func (h *handler) getBankAccountListAgentHandler(w http.ResponseWriter, r *http.
 	}
 }
 
+// @Summary Создать банковский счет агента
+// @Description Создание нового банковского счета для агента
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param request body rmodel.BankAccountCreateRequest true "Данные банковского счета"
+// @Success 201 {object} rmodel.BankAccountCreateResponse "Банковский счет создан"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/bank_accounts [post]
 func (h *handler) createBankAccountAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "createBankAccountAgentHandler"
 
@@ -232,6 +289,19 @@ func (h *handler) createBankAccountAgentHandler(w http.ResponseWriter, r *http.R
 	}
 }
 
+// @Summary Обновить банковский счет агента
+// @Description Обновление информации о банковском счете агента
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param bank_account_id path string true "ID банковского счета"
+// @Param request body rmodel.BankAccountUpdateRequest true "Данные для обновления"
+// @Success 200 {object} map[string]string "Банковский счет обновлен"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/bank_accounts/{bank_account_id} [put]
 func (h *handler) updateBankAccountAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "updateBankAccountAgentHandler"
 
@@ -285,6 +355,18 @@ func (h *handler) updateBankAccountAgentHandler(w http.ResponseWriter, r *http.R
 }
 
 // TODO: test when implemented
+// @Summary Удалить банковский счет агента
+// @Description Удаление банковского счета агента
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param bank_account_id path string true "ID банковского счета"
+// @Success 200 {object} map[string]string "Банковский счет удален"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/bank_accounts/{bank_account_id} [delete]
 func (h *handler) deleteBankAccountAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "deleteBankAccountAgentHandler"
 
@@ -327,6 +409,17 @@ func (h *handler) deleteBankAccountAgentHandler(w http.ResponseWriter, r *http.R
 	}
 }
 
+// @Summary Получить баланс дистрибьютора
+// @Description Получение текущего баланса дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Success 200 {object} rmodel.BalanceGetResponse "Баланс дистрибьютора"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/balance [get]
 func (h *handler) getBalanceDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getBalanceDistributorHandler"
 
@@ -359,6 +452,18 @@ func (h *handler) getBalanceDistributorHandler(w http.ResponseWriter, r *http.Re
 	}
 }
 
+// @Summary Получить баланс компании дистрибьютора
+// @Description Получение баланса конкретной компании дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Success 200 {object} rmodel.BalanceGetResponse "Баланс компании"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id}/balance [get]
 func (h *handler) getCompanyBalanceDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getCompanyBalanceDistributorHandler"
 
@@ -391,6 +496,17 @@ func (h *handler) getCompanyBalanceDistributorHandler(w http.ResponseWriter, r *
 	}
 }
 
+// @Summary Получить список транзакций дистрибьютора
+// @Description Получение списка транзакций дистрибьютора с возможностью фильтрации
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Success 200 {object} rmodel.TransactionListGetResponse "Список транзакций"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/transactions [get]
 func (h *handler) getTransactionListDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getTransactionListDistributorHandler"
 
@@ -434,6 +550,18 @@ func (h *handler) getTransactionListDistributorHandler(w http.ResponseWriter, r
 	}
 }
 
+// @Summary Получить список транзакций компании дистрибьютора
+// @Description Получение списка транзакций конкретной компании дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Success 200 {object} rmodel.TransactionListGetResponse "Список транзакций компании"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id}/transactions [get]
 func (h *handler) getCompanyTransactionListDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getCompanyTransactionListDistributorHandler"
 
@@ -477,6 +605,18 @@ func (h *handler) getCompanyTransactionListDistributorHandler(w http.ResponseWri
 	}
 }
 
+// @Summary Создать транзакцию дистрибьютора
+// @Description Создание новой транзакции для дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param request body rmodel.TransactionCreateRequest true "Данные транзакции"
+// @Success 201 {object} rmodel.TransactionCreateResponse "Транзакция создана"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/transactions [post]
 func (h *handler) createTransactionDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "createTransactionDistributorHandler"
 
@@ -539,6 +679,17 @@ func (h *handler) createTransactionDistributorHandler(w http.ResponseWriter, r *
 	}
 }
 
+// @Summary Получить список банковских счетов дистрибьютора
+// @Description Получение списка банковских счетов дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Success 200 {object} rmodel.BankAccountListGetResponse "Список банковских счетов"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/bank_accounts [get]
 func (h *handler) getBankAccountListDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getBankAccountListDistributorHandler"
 
@@ -571,6 +722,18 @@ func (h *handler) getBankAccountListDistributorHandler(w http.ResponseWriter, r
 	}
 }
 
+// @Summary Получить список банковских счетов компании дистрибьютора
+// @Description Получение списка банковских счетов конкретной компании дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Success 200 {object} rmodel.BankAccountListGetResponse "Список банковских счетов компании"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id}/bank_accounts [get]
 func (h *handler) getCompanyBankAccountListDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getCompanyBankAccountListDistributorHandler"
 
@@ -603,6 +766,19 @@ func (h *handler) getCompanyBankAccountListDistributorHandler(w http.ResponseWri
 	}
 }
 
+// @Summary Создать банковский счет компании дистрибьютора
+// @Description Создание нового банковского счета для компании дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Param request body rmodel.BankAccountCreateRequest true "Данные банковского счета"
+// @Success 201 {object} rmodel.BankAccountCreateResponse "Банковский счет создан"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id}/bank_accounts [post]
 func (h *handler) createBankAccountDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "createBankAccountDistributorHandler"
 
@@ -664,6 +840,19 @@ func (h *handler) createBankAccountDistributorHandler(w http.ResponseWriter, r *
 	}
 }
 
+// @Summary Обновить банковский счет дистрибьютора
+// @Description Обновление информации о банковском счете дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param bank_account_id path string true "ID банковского счета"
+// @Param request body rmodel.BankAccountUpdateRequest true "Данные для обновления"
+// @Success 200 {object} map[string]string "Банковский счет обновлен"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/bank_accounts/{bank_account_id} [put]
 func (h *handler) updateBankAccountDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "updateBankAccountDistributorHandler"
 
@@ -725,6 +914,18 @@ func (h *handler) updateBankAccountDistributorHandler(w http.ResponseWriter, r *
 	}
 }
 
+// @Summary Удалить банковский счет дистрибьютора
+// @Description Удаление банковского счета дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param bank_account_id path string true "ID банковского счета"
+// @Success 200 {object} map[string]string "Банковский счет удален"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/bank_accounts/{bank_account_id} [delete]
 func (h *handler) deleteBankAccountDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "deleteBankAccountDistributorHandler"
 

internal/http/build_info.go

@@ -5,6 +5,13 @@ import (
 	"net/http"
 )
 
+// @Summary Получить информацию о сборке
+// @Description Получение информации о версии, коммите и дате сборки приложения
+// @Tags system
+// @Accept json
+// @Produce json
+// @Success 200 {object} map[string]string "Информация о сборке"
+// @Router /api/v1/healthcheck [get]
 func (h *handler) getBuildInfoHandler(w http.ResponseWriter, _ *http.Request) {
 	response := struct {
 		Version string `json:"version"`

internal/http/company_agent.go

@@ -12,6 +12,18 @@ import (
 	rmodel "git-molva.ru/Molva/molva-backend/services/api_gateway/internal/request_model"
 )
 
+// @Summary Получить список компаний агента
+// @Description Получение списка всех компаний, принадлежащих агенту
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Success 200 {object} rmodel.CompanyListGetResponse "Список компаний"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/companies [get]
 func (h *handler) getCompanyListAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getCompanyListAgentHandler"
 
@@ -44,6 +56,20 @@ func (h *handler) getCompanyListAgentHandler(w http.ResponseWriter, r *http.Requ
 	}
 }
 
+// @Summary Получить компанию по ID
+// @Description Получение детальной информации о компании агента
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param company_id path string true "ID компании"
+// @Success 200 {object} rmodel.CompanyByIdGetResponse "Информация о компании"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 404 {object} map[string]string "Компания не найдена"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/company/{company_id} [get]
 func (h *handler) getCompanyByIdAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getCompanyByIdAgentHandler"
 
@@ -78,6 +104,19 @@ func (h *handler) getCompanyByIdAgentHandler(w http.ResponseWriter, r *http.Requ
 	}
 }
 
+// @Summary Создать компанию
+// @Description Создание новой компании для агента
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param request body rmodel.CompanyCreateRequest true "Данные для создания компании"
+// @Success 201 {object} rmodel.CompanyCreateResponse "Компания создана"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/company [post]
 // FIXME: foreign key violation review
 func (h *handler) createCompanyAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "createAgentCompanyHandler"

internal/http/company_distributor.go

@@ -10,6 +10,18 @@ import (
 	"github.com/gorilla/mux"
 )
 
+// @Summary Получить список компаний дистрибьютора
+// @Description Получение списка всех компаний, принадлежащих дистрибьютору
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Success 200 {object} rmodel.CompanyListGetResponse "Список компаний"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/companies [get]
 func (h *handler) getCompanyListDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getCompanyListDistributorHandler"
 
@@ -42,6 +54,20 @@ func (h *handler) getCompanyListDistributorHandler(w http.ResponseWriter, r *htt
 	}
 }
 
+// @Summary Получить компанию дистрибьютора по ID
+// @Description Получение детальной информации о компании дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Success 200 {object} rmodel.CompanyByIdGetResponse "Информация о компании"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 404 {object} map[string]string "Компания не найдена"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id} [get]
 func (h *handler) getCompanyByIdDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getCompanyByIdDistributorHandler"
 
@@ -76,6 +102,19 @@ func (h *handler) getCompanyByIdDistributorHandler(w http.ResponseWriter, r *htt
 	}
 }
 
+// @Summary Создать компанию дистрибьютора
+// @Description Создание новой компании для дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param request body rmodel.CompanyCreateRequest true "Данные для создания компании"
+// @Success 201 {object} rmodel.CompanyCreateResponse "Компания создана"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company [post]
 func (h *handler) createCompanyDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "createCompanyDistributorHandler"
 
@@ -124,6 +163,21 @@ func (h *handler) createCompanyDistributorHandler(w http.ResponseWriter, r *http
 	}
 }
 
+// @Summary Обновить компанию дистрибьютора
+// @Description Обновление информации о компании дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Param request body rmodel.CompanyUpdateRequest true "Данные для обновления"
+// @Success 204 "Компания обновлена"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 404 {object} map[string]string "Компания не найдена"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id} [patch]
 func (h *handler) updateCompanyDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "updateCompanyDistributorHandler"
 
@@ -161,6 +215,21 @@ func (h *handler) updateCompanyDistributorHandler(w http.ResponseWriter, r *http
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// @Summary Добавить участника в компанию
+// @Description Добавление нового участника в компанию дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Param request body rmodel.AddDistributorCompanyMemberRequest true "Данные участника"
+// @Success 201 "Участник добавлен"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 404 {object} map[string]string "Компания не найдена"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id} [post]
 func (h *handler) addCompanyMemberDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "addCompanyMemberDistributorHandler"
 

internal/http/handlers.go

@@ -32,6 +32,19 @@ import (
 	"github.com/gorilla/mux"
 )
 
+// @Summary Получить персональную ссылку
+// @Description Получение персональной ссылки агента для вакансии
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param vacancy_id path string true "ID вакансии"
+// @Success 200 {object} types.PersonalLinkResponse "Персональная ссылка"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/vacancies/{vacancy_id} [get]
 func (h *handler) getPersonalLinkHandler(w http.ResponseWriter, r *http.Request) {
 	handlerName := "getPersonalLinkHandler"
 	vars := mux.Vars(r)
@@ -70,6 +83,18 @@ func (h *handler) getPersonalLinkHandler(w http.ResponseWriter, r *http.Request)
 	}
 }
 
+// @Summary Получить анкету
+// @Description Получение HTML формы анкеты для клиента
+// @Tags clients
+// @Accept json
+// @Produce text/html
+// @Param link query string true "Зашифрованная ссылка с параметрами"
+// @Success 200 {string} string "HTML форма анкеты"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 404 {object} map[string]string "Вакансия не найдена"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/anketa [get]
+//
 //nolint:funlen // TODO: make it sudo super clean
 func (h *handler) getAnketaHandler(w http.ResponseWriter, r *http.Request) {
 	handlerName := "getAnketaHandler"
@@ -235,6 +260,19 @@ func (h *handler) extractPermissions(permMap *auth.GetPermissionsByUsersIdRespon
 	return perm
 }
 
+// @Summary Получить список сотрудников компании
+// @Description Получение списка сотрудников компании
+// @Tags employees
+// @Accept json
+// @Produce json
+// @Param company_id path string true "ID компании"
+// @Param uid query string true "ID пользователя"
+// @Success 200 {object} rmodel.EmployeeResponse "Список сотрудников"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/companies/{company_id}/employees [get]
 func (h *handler) getEmployeesHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getEmployeesHandler"
 
@@ -292,6 +330,16 @@ func (h *handler) getEmployeesHandler(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+// @Summary Получить статус валидации пользователя
+// @Description Получение статуса валидации пользователя по UID
+// @Tags system
+// @Accept json
+// @Produce json
+// @Param uid path string true "UID пользователя"
+// @Success 200 {object} map[string]string "Статус валидации"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/{uid}/validation [get]
 func (h *handler) getUserValidationStatusHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getValidationStatusHandler"
 
@@ -331,6 +379,16 @@ func (h *handler) getUserValidationStatusHandler(w http.ResponseWriter, r *http.
 	}
 }
 
+// @Summary Получить файл документа
+// @Description Получение файла документа по имени
+// @Tags system
+// @Accept json
+// @Produce application/octet-stream
+// @Param file path string true "Имя файла"
+// @Success 200 {file} file "Файл документа"
+// @Failure 404 {object} map[string]string "Файл не найден"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/docs/{file} [get]
 func (h *handler) getFileHandler(w http.ResponseWriter, r *http.Request) {
 	vars := mux.Vars(r)
 	fileName := vars["file"]
@@ -389,6 +447,17 @@ func (h *handler) getFileHandler(w http.ResponseWriter, r *http.Request) {
 	_, _ = w.Write([]byte(link))
 }
 
+// @Summary Подтверждение email
+// @Description Подтверждение email адреса пользователя по токену
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param uid query string true "ID пользователя"
+// @Param token query string true "Токен подтверждения"
+// @Success 200 {object} map[string]string "Email успешно подтвержден"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/verify_email [patch]
 func (h *handler) verifyEmailHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "verifyEmailHandler"
 
@@ -528,6 +597,16 @@ func (h *handler) sendNewUserNotificationToAdmin(userInfo *auth.UserInfo, userNa
 	return nil
 }
 
+// @Summary Статус подтверждения email
+// @Description Получение статуса подтверждения email адреса пользователя
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param uid query string true "ID пользователя"
+// @Success 200 {object} map[string]string "Статус подтверждения email"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/verify_email [get]
 func (h *handler) getEmailVerificationStatusHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getEmailVerificationStatusHandler"
 
@@ -638,6 +717,23 @@ func (h *handler) validateEmail(email string) (bool, error) {
 	return isValidEmail, nil
 }
 
+// @Summary Получить события пользователя
+// @Description Получение ленты событий пользователя с возможностью фильтрации
+// @Tags feed
+// @Accept json
+// @Produce json
+// @Param uid path string true "ID пользователя"
+// @Param user_type query string true "Тип пользователя (agent/distributor)"
+// @Param event_type query string false "Тип события (через запятую)"
+// @Param show_cancelled query bool false "Показывать отмененные события"
+// @Param limit query int false "Лимит событий"
+// @Param offset query int false "Смещение"
+// @Success 200 {object} []feed.Event "Список событий"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/feed/{uid}/events [get]
 func (h *handler) GetUserEventsHandler(w http.ResponseWriter, r *http.Request) {
 	handlerName := "GetUserEventsHandler"
 	query := r.URL.Query()

internal/http/integration.go

@@ -11,6 +11,16 @@ import (
 	intrmodel "git-molva.ru/Molva/molva-backend/services/api_gateway/internal/request_model/integration"
 )
 
+// @Summary Callback интеграции с ВкусВилл
+// @Description Обработка callback запросов от интеграции с ВкусВилл
+// @Tags integration
+// @Accept json
+// @Produce json
+// @Param request body map[string]interface{} true "Данные callback от ВкусВилл"
+// @Success 200 {object} map[string]string "Callback обработан"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/integration/vkusvill/callback [post]
 func (h *handler) vkusvillIntegrationCallbackHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "vkusvillIntegrationCallbackHandler"
 

internal/http/logo.go

@@ -130,6 +130,19 @@ func (lf *LogoFile) Reset() error {
 
 // =============== LOGO HANDLERS ===============
 
+// @Summary Получить логотип компании
+// @Description Получение логотипа компании дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Success 200 {file} file "Логотип компании"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 404 {object} map[string]string "Логотип не найден"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id}/logo [get]
 func (h *handler) getCompanyLogoHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getCompanyLogoHandler"
 
@@ -180,6 +193,19 @@ func (h *handler) getCompanyLogoHandler(w http.ResponseWriter, r *http.Request)
 	}
 }
 
+// @Summary Создать логотип компании
+// @Description Загрузка нового логотипа для компании дистрибьютора
+// @Tags distributors
+// @Accept multipart/form-data
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Param logo formData file true "Файл логотипа"
+// @Success 201 {object} map[string]string "Логотип загружен"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id}/logo [post]
 func (h *handler) createCompanyLogoHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "createCompanyLogoHandler"
 
@@ -240,6 +266,19 @@ func (h *handler) createCompanyLogoHandler(w http.ResponseWriter, r *http.Reques
 	w.WriteHeader(http.StatusCreated)
 }
 
+// @Summary Обновить логотип компании
+// @Description Обновление логотипа компании дистрибьютора
+// @Tags distributors
+// @Accept multipart/form-data
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Param logo formData file true "Новый файл логотипа"
+// @Success 200 {object} map[string]string "Логотип обновлен"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id}/logo [put]
 func (h *handler) updateCompanyLogoHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "updateCompanyLogoHandler"
 
@@ -300,6 +339,18 @@ func (h *handler) updateCompanyLogoHandler(w http.ResponseWriter, r *http.Reques
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// @Summary Удалить логотип компании
+// @Description Удаление логотипа компании дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id path string true "ID компании"
+// @Success 200 {object} map[string]string "Логотип удален"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/company/{company_id}/logo [delete]
 func (h *handler) deleteCompanyLogoHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "deleteCompanyLogoHandler"
 

internal/http/profile.go

@@ -12,6 +12,17 @@ import (
 	rmodel "git-molva.ru/Molva/molva-backend/services/api_gateway/internal/request_model"
 )
 
+// @Summary Получить профиль агента
+// @Description Получение профиля агента по ID
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Success 200 {object} rmodel.ProfileGetResponse "Профиль агента"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/profile [get]
 func (h *handler) getProfileAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getAgentProfileHandler"
 
@@ -44,6 +55,18 @@ func (h *handler) getProfileAgentHandler(w http.ResponseWriter, r *http.Request)
 	}
 }
 
+// @Summary Обновить профиль агента
+// @Description Обновление профиля агента
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param request body rmodel.ProfileUpdateRequest true "Данные для обновления профиля"
+// @Success 200 {object} map[string]string "Профиль обновлен"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/profile [put]
 func (h *handler) updateProfileAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "setAgentProfileHandler"
 
@@ -86,6 +109,17 @@ func (h *handler) updateProfileAgentHandler(w http.ResponseWriter, r *http.Reque
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// @Summary Получить профиль дистрибьютора
+// @Description Получение профиля дистрибьютора по ID
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Success 200 {object} rmodel.ProfileGetResponse "Профиль дистрибьютора"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/profile [get]
 func (h *handler) getProfileDisributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getProfileDisributorHandler"
 
@@ -118,6 +152,18 @@ func (h *handler) getProfileDisributorHandler(w http.ResponseWriter, r *http.Req
 	}
 }
 
+// @Summary Обновить профиль дистрибьютора
+// @Description Обновление профиля дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param request body rmodel.ProfileUpdateRequest true "Данные для обновления профиля"
+// @Success 200 {object} map[string]string "Профиль обновлен"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/profile [put]
 func (h *handler) updateProfileDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "updateProfileDistributorHandler"
 

internal/http/router.go

@@ -23,7 +23,9 @@ import (
 	formgenerator "git-molva.ru/Molva/molva-backend/services/api_gateway/internal/form_generator"
 
 	"git-molva.ru/Molva/molva-backend/services/api_gateway/internal/config"
+	_ "git-molva.ru/Molva/molva-backend/services/api_gateway/internal/http/swagger/docs"
 	"github.com/gorilla/mux"
+	httpSwagger "github.com/swaggo/http-swagger"
 )
 
 type Router struct {
@@ -200,6 +202,9 @@ func SetupRouter(r *Router, buildCfg config.BuildInfo) {
 
 	// --------------- FEED ------------
 	subRouter.HandleFunc("/feed/{uid}/events", h.GetUserEventsHandler).Methods(http.MethodGet)
+
+	// --------------- SWAGGER UI ------------
+	r.Mux.PathPrefix("/swagger/").Handler(httpSwagger.WrapHandler)
 }
 
 func setupAuthHandlers(r *Router, h *handler) {

internal/http/submission.go

@@ -18,6 +18,22 @@ import (
 	rmodel "git-molva.ru/Molva/molva-backend/services/api_gateway/internal/request_model"
 )
 
+// @Summary Получить список заявок агента
+// @Description Получение списка заявок агента с возможностью фильтрации
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param vacancy_id query string false "ID вакансии"
+// @Param status query string false "Статус заявки"
+// @Param page query int false "Номер страницы"
+// @Param page_size query int false "Размер страницы"
+// @Success 200 {object} rmodel.SubmissionListGetResponse "Список заявок"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/submissions [get]
 func (h *handler) getSubmissionListAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getSubmissionListAgentHandler"
 
@@ -58,6 +74,20 @@ func (h *handler) getSubmissionListAgentHandler(w http.ResponseWriter, r *http.R
 	}
 }
 
+// @Summary Получить CV заявки
+// @Description Получение CV файла заявки
+// @Tags agents
+// @Accept json
+// @Produce application/octet-stream
+// @Param agent_id path string true "ID агента"
+// @Param submission_id path string true "ID заявки"
+// @Success 200 {file} file "CV файл"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 404 {object} map[string]string "CV не найден"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/submissions/{submission_id}/cv [get]
 func (h *handler) getSubmissionCVHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getSubmissionCVHandler"
 
@@ -121,6 +151,20 @@ func (h *handler) getSubmissionCVHandler(w http.ResponseWriter, r *http.Request)
 	}
 }
 
+// @Summary Удалить заявку агента
+// @Description Удаление заявки агента
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param submission_id path string true "ID заявки"
+// @Success 204 "Заявка удалена"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 404 {object} map[string]string "Заявка не найдена"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/submissions/{submission_id} [delete]
 func (h *handler) deleteSubmissionAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "deleteSubmissionHandler"
 
@@ -162,6 +206,22 @@ func (h *handler) deleteSubmissionAgentHandler(w http.ResponseWriter, r *http.Re
 	}
 }
 
+// @Summary Получить список заявок дистрибьютора
+// @Description Получение списка заявок дистрибьютора с возможностью фильтрации
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param vacancy_id path string true "ID вакансии"
+// @Param status query string false "Статус заявки"
+// @Param page query int false "Номер страницы"
+// @Param page_size query int false "Размер страницы"
+// @Success 200 {object} rmodel.SubmissionListGetResponse "Список заявок"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/vacancies/{vacancy_id}/submissions [get]
 func (h *handler) getSubmissionListDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getSubmissionsDistributorHandler"
 
@@ -205,6 +265,22 @@ func (h *handler) getSubmissionListDistributorHandler(w http.ResponseWriter, r *
 	}
 }
 
+// @Summary Обновить статус заявки
+// @Description Обновление статуса заявки дистрибьютором
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param vacancy_id path string true "ID вакансии"
+// @Param submission_id path string true "ID заявки"
+// @Param request body rmodel.SubmissionStatusUpdateRequest true "Новый статус заявки"
+// @Success 200 "Статус обновлен"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 404 {object} map[string]string "Заявка не найдена"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/vacancies/{vacancy_id}/submissions/{submission_id}/status [post]
 func (h *handler) updateSubmissionStatusDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "updateSubmissionStatusDistributorHandler"
 
@@ -243,6 +319,17 @@ func (h *handler) updateSubmissionStatusDistributorHandler(w http.ResponseWriter
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// @Summary Отправить анкету
+// @Description Отправка заполненной анкеты клиента
+// @Tags clients
+// @Accept json
+// @Produce json
+// @Param request body map[string]interface{} true "Данные анкеты"
+// @Success 201 {object} map[string]string "Анкета отправлена"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/anketa [post]
+//
 //nolint:funlen // TODO: refactor
 func (h *handler) postAnketaHandler(w http.ResponseWriter, r *http.Request) {
 	handlerName := "postAnketaHandler"

internal/http/swagger/models.go

@@ -0,0 +1,14 @@
+package swagger
+
+// ErrorResponse представляет стандартный ответ об ошибке
+type ErrorResponse struct {
+	Error   string `json:"error" example:"Bad Request"`
+	Message string `json:"message" example:"Invalid request parameters"`
+	Code    int    `json:"code" example:"400"`
+}
+
+// SuccessResponse представляет стандартный ответ об успехе
+type SuccessResponse struct {
+	Message string `json:"message" example:"Operation completed successfully"`
+	Code    int    `json:"code" example:"200"`
+}

internal/http/vacancy.go

@@ -34,6 +34,27 @@ func (h *handler) setVacancyLogoLinks(
 	}
 }
 
+// @Summary Получить список вакансий для агента
+// @Description Получение списка вакансий с возможностью фильтрации
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param distributor_id query string false "ID дистрибьютора"
+// @Param company_id query string false "ID компании"
+// @Param region query string false "Регион"
+// @Param salary_bottom query int false "Минимальная зарплата"
+// @Param salary_top query int false "Максимальная зарплата"
+// @Param is_archived query bool false "Архивные вакансии"
+// @Param status query string false "Статус вакансии"
+// @Param page query int false "Номер страницы"
+// @Param page_size query int false "Размер страницы"
+// @Success 200 {object} rmodel.VacancyListGetResponse "Список вакансий"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/vacancies [get]
 func (h *handler) getVacancyListAgentHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getVacancyListAgentHandler"
 
@@ -71,6 +92,26 @@ func (h *handler) getVacancyListAgentHandler(w http.ResponseWriter, r *http.Requ
 	}
 }
 
+// @Summary Получить список вакансий дистрибьютора
+// @Description Получение списка вакансий дистрибьютора с возможностью фильтрации
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param company_id query string false "ID компании"
+// @Param region query string false "Регион"
+// @Param salary_bottom query int false "Минимальная зарплата"
+// @Param salary_top query int false "Максимальная зарплата"
+// @Param is_archived query bool false "Архивные вакансии"
+// @Param status query string false "Статус вакансии"
+// @Param page query int false "Номер страницы"
+// @Param page_size query int false "Размер страницы"
+// @Success 200 {object} rmodel.VacancyListGetResponse "Список вакансий"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/vacancies [get]
 func (h *handler) getVacancyListDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getVacancyListDistributorHandler"
 
@@ -106,6 +147,19 @@ func (h *handler) getVacancyListDistributorHandler(w http.ResponseWriter, r *htt
 	}
 }
 
+// @Summary Создать вакансию
+// @Description Создание новой вакансии дистрибьютором
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param request body rmodel.VacancyCreateRequest true "Данные для создания вакансии"
+// @Success 201 {object} rmodel.VacancyCreateResponse "Вакансия создана"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/vacancies [post]
 func (h *handler) createVacancyDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "createVacancyDistributorHandler"
 
@@ -158,6 +212,21 @@ func (h *handler) createVacancyDistributorHandler(w http.ResponseWriter, r *http
 	}
 }
 
+// @Summary Обновить вакансию
+// @Description Обновление информации о вакансии дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param vacancy_id path string true "ID вакансии"
+// @Param request body rmodel.VacancyUpdateRequest true "Данные для обновления"
+// @Success 204 "Вакансия обновлена"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 404 {object} map[string]string "Вакансия не найдена"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/vacancies/{vacancy_id} [patch]
 func (h *handler) updateVacancyDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "updateVacancyDistributorHandler"
 
@@ -201,6 +270,20 @@ func (h *handler) updateVacancyDistributorHandler(w http.ResponseWriter, r *http
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// @Summary Удалить вакансию
+// @Description Удаление вакансии дистрибьютора
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param vacancy_id path string true "ID вакансии"
+// @Success 204 "Вакансия удалена"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 404 {object} map[string]string "Вакансия не найдена"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/vacancies/{vacancy_id} [delete]
 func (h *handler) deleteVacancyDistributorHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "deleteDistributorVacancyHandler"
 
@@ -235,6 +318,18 @@ func (h *handler) deleteVacancyDistributorHandler(w http.ResponseWriter, r *http
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// @Summary Отправить вакансию на модерацию
+// @Description Отправка вакансии дистрибьютора на модерацию
+// @Tags distributors
+// @Accept json
+// @Produce json
+// @Param distributor_id path string true "ID дистрибьютора"
+// @Param vacancy_id path string true "ID вакансии"
+// @Success 200 {object} map[string]string "Вакансия отправлена на модерацию"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/distributor/{distributor_id}/vacancies/{vacancy_id}/moderation [post]
 func (h *handler) sendVacancyToModerationHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "sendVacancyToModerationHandler"