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

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: