Покрытие кода docstrings

SRV/api/router.py

@@ -1,3 +1,27 @@
+"""
+Маршрутизация API-версии v1 для GONETS.
+
+Модуль агрегирует и монтирует роутеры отдельных доменных областей под общим
+корневым роутером. Каждый подключенный модуль предоставляет набор эндпоинтов
+со своим префиксом и тегами для группировки в документации FastAPI.
+
+Структура маршрутов:
+ - `/ufw` (UFW): управление правилами и состоянием Uncomplicated Firewall.
+ - `/ip` (IP): проверки и применение IP-конфигураций для сетевых профилей.
+ - `/network` (Network): получение и визуализация состояния интерфейсов,
+   управление позициями UI-контейнеров.
+ - `/auth` (Auth): регистрация, аутентификация (JWT), сессии.
+ - `/subnet` (Subnet): сканирование подсетей, заметки к устройствам,
+   взаимодействие с Wi‑Fi (скан/подключение/отключение/статус).
+ - `WebSocket`: обработчики взаимодействия по WS (без префикса, путь внутри
+   модуля), периодическая трансляция сетевых данных.
+ - `/settings` (Settings): сервисные операции над локальными JSON‑хранилищами
+   (очистка данных подсетей/wi‑fi и пр.).
+
+Назначение:
+ - Централизованная точка подключения доменных роутеров к приложению.
+ - Единообразие тегов и префиксов для автогенерации схемы и документации.
+"""
 from fastapi import APIRouter
 from .v1 import ufw, websocket, ip, network, auth, subnet, settings
 

SRV/api/v1/ufw.py

@@ -15,8 +15,17 @@ class RuleNumbers(BaseModel):
 
 @router.get("/rules", response_model=UFWRulesResponse)
 async def get_ufw_rules():
-    """
-    Получает все правила UFW с помощью сервиса UFWService и возвращает их в формате JSON.
+    """Возвращает все правила UFW.
+
+    Осуществляет обращение к сервису `UFWService` для чтения текущего списка
+    правил брандмауэра и возвращает результат в сериализованном виде для клиента.
+
+    Returns:
+        UFWRulesResponse: Структура с коллекцией правил и сопутствующей
+        информацией о состоянии.
+
+    Raises:
+        HTTPException: В случае ошибок взаимодействия с UFW (status_code=500).
     """
     ufw_service = UFWService()
     try:
@@ -27,8 +36,13 @@ async def get_ufw_rules():
 
 @router.get("/status", response_model=UFWStatus)
 async def get_ufw_status():
-    """
-    Получает текущий статус UFW.
+    """Возвращает текущий статус UFW.
+
+    Returns:
+        UFWStatus: Объект со сведениями о включенности UFW и деталями статуса.
+
+    Raises:
+        HTTPException: Если не удалось получить статус (status_code=500).
     """
     ufw_service = UFWService()
     try:
@@ -39,8 +53,13 @@ async def get_ufw_status():
 
 @router.post("/enable")
 async def enable_ufw():
-    """
-    Включает UFW.
+    """Включает UFW.
+
+    Returns:
+        dict: Словарь с ключами `status` и `message` при успешном выполнении.
+
+    Raises:
+        HTTPException: Если включение завершилось неуспешно (status_code=500).
     """
     ufw_service = UFWService()
     try:
@@ -56,8 +75,13 @@ async def enable_ufw():
 
 @router.post("/disable")
 async def disable_ufw():
-    """
-    Выключает UFW.
+    """Выключает UFW.
+
+    Returns:
+        dict: Словарь с ключами `status` и `message` при успешном выполнении.
+
+    Raises:
+        HTTPException: Если выключение завершилось неуспешно (status_code=500).
     """
     ufw_service = UFWService()
     try:
@@ -73,8 +97,19 @@ async def disable_ufw():
 
 @router.post("/rules/in")
 async def add_ufw_in_rules(rules: List[UFWRule]):
-    """
-    Добавляет входящие (in) правила UFW.
+    """Добавляет входящие (in) правила UFW.
+
+    Args:
+        rules (List[UFWRule]): Список правил, определяющих направления,
+            порты/диапазоны/протоколы и действия (allow/deny/reject).
+
+    Returns:
+        dict: Итог выполнения с количеством успешно добавленных правил и деталями
+        по каждому правилу.
+
+    Raises:
+        HTTPException: Если UFW отключен (status_code=400) или при внутренних
+        ошибках (status_code=500).
     """
     ufw_service = UFWService()
     try:
@@ -108,8 +143,17 @@ async def add_ufw_in_rules(rules: List[UFWRule]):
 
 @router.post("/rules/out")
 async def add_ufw_out_rules(rules: List[UFWRule]):
-    """
-    Добавляет исходящие (out) правила UFW.
+    """Добавляет исходящие (out) правила UFW.
+
+    Args:
+        rules (List[UFWRule]): Список правил исходящего трафика для добавления.
+
+    Returns:
+        dict: Объект статуса с сообщением об успешном добавлении.
+
+    Raises:
+        HTTPException: Если UFW отключен (status_code=400) или при внутренних
+        ошибках (status_code=500).
     """
     ufw_service = UFWService()
     try:
@@ -137,8 +181,18 @@ async def add_ufw_out_rules(rules: List[UFWRule]):
 
 @router.delete("/rules")
 async def delete_ufw_rules(rule_numbers: RuleNumbers):
-    """
-    Удаляет правила UFW по их номерам.
+    """Удаляет правила UFW по их номерам.
+
+    Args:
+        rule_numbers (RuleNumbers): Номера правил, подлежащих удалению (как в
+            выводе `ufw status numbered`).
+
+    Returns:
+        dict: Информация об общем количестве удаляемых правил, числе успешных и
+        возможной ошибке.
+
+    Raises:
+        HTTPException: При ошибках удаления (status_code=500).
     """
     ufw_service = UFWService()
     try: