improve docstring for swagger readability

backend/maelstro/common/models.py

@@ -1,4 +1,5 @@
-from typing import Any, Optional
+from datetime import datetime
+from typing import Any, Optional, Annotated
 from pydantic import BaseModel, Field
 
 
@@ -7,3 +8,131 @@ class SearchQuery(BaseModel):
     source_: Optional[list[str]] = Field([], alias="_source")
     from_: Optional[int] = Field(0, alias="from")
     size: Optional[int] = 20
+
+
+user_response_description = """
+User related x-Headers:
+- username: User name
+- org: User organization
+- roles: User roles
+- external-authentication: External authentication
+- proxy: Proxy
+- orgname: Organization name
+"""
+
+
+class UserResponse(BaseModel):
+    """
+    User related x-Headers:
+    - sec_username: User name
+    - sec_org: User organization
+    - sec_roles: User roles
+    - sec_external_authentication: External authentication
+    - sec_proxy: Proxy
+    - sec_orgname: Organization name
+    """
+
+    username: Optional[str]
+    org: Optional[str]
+    roles: Optional[str]
+    external_authentication: Annotated[
+        Optional[str], Field(None, serialization_alias="external-authentication")
+    ]
+    proxy: Optional[str]
+    orgname: Optional[str]
+
+
+class SourcesResponseElement(BaseModel):
+    name: str
+    url: str
+
+
+class DestinationsResponseElement(BaseModel):
+    name: str
+    gn_url: str
+    gs_url: str
+
+
+class RegisteredTransformation(BaseModel):
+    xsl_path: str
+    description: str
+
+
+class TransformationResponse(BaseModel):
+    registered_transformations: Annotated[
+        dict[str, RegisteredTransformation],
+        Field({}, serialization_alias="Registered transformations"),
+    ]
+    transformation_paths: Annotated[
+        Optional[dict[str, list[RegisteredTransformation]]],
+        Field({}, serialization_alias="Transformation paths"),
+    ]
+
+
+class Metadata(BaseModel):
+    title: str
+    iso_standard: Optional[str] = ""
+
+
+class LinkedLayer(BaseModel):
+    server_url: str
+    name: str
+    description: str
+    protocol: str
+
+
+class PreviewGN(BaseModel):
+    src: str
+    dst: str
+    metadata: list[Metadata]
+
+
+class PreviewGS(BaseModel):
+    src: str
+    dst: str
+    layers: list[str]
+    styles: list[str]
+
+
+class PreviewClone(BaseModel):
+    geonetwork_resources: list[PreviewGN]
+    geoserver_resources: list[PreviewGS]
+
+
+class JsonLogRecord(BaseModel):
+    id: int
+    start_time: datetime
+    end_time: datetime
+    first_name: str
+    last_name: str
+    status_code: int
+    dataset_uuid: str
+    src_name: str
+    dst_name: str
+    src_title: str
+    dst_title: str
+    copy_meta: bool
+    copy_layers: bool
+    copy_styles: bool
+    details: Optional[list[dict[str, Any]]] = []
+
+
+sample_json_log_records = [
+    {
+        "id": 97,
+        "start_time": "2025-02-07T17:00:48.232023",
+        "end_time": "2025-02-07T17:00:49.537302",
+        "first_name": "",
+        "last_name": "",
+        "status_code": 200,
+        "dataset_uuid": "4d6318d8-de30-4af5-8f37-971c486a0280",
+        "src_name": "GeonetworkRennes",
+        "dst_name": "CompoLocale",
+        "src_title": "Schéma Directeur Vélo Métropolitain de Rennes Métropole",
+        "dst_title": "Schéma Directeur Vélo Métropolitain de Rennes Métropole",
+        "copy_meta": True,
+        "copy_layers": False,
+        "copy_styles": False,
+        "details": [],
+    },
+]

backend/maelstro/config/config.py

@@ -4,6 +4,7 @@
 from functools import cache
 from typing import Any
 from maelstro.common.types import Credentials, DbConfig
+from maelstro.common.models import SourcesResponseElement, DestinationsResponseElement
 
 
 class ConfigError(Exception):
@@ -55,22 +56,22 @@ def read_all_credentials(self) -> None:
                 geor_instance["geoserver"], common_credentials
             )
 
-    def get_gn_sources(self) -> list[dict[str, str]]:
+    def get_gn_sources(self) -> list[SourcesResponseElement]:
         return [
-            {"name": gn["name"], "url": gn["api_url"]}
+            SourcesResponseElement(name=gn["name"], url=gn["api_url"])
             for gn in self.config["sources"]["geonetwork_instances"]
         ]
 
     def get_gs_sources(self) -> list[str]:
         return [gs["url"] for gs in self.config["sources"]["geoserver_instances"]]
 
-    def get_destinations(self) -> list[dict[str, str]]:
+    def get_destinations(self) -> list[DestinationsResponseElement]:
         return [
-            {
-                "name": k,
-                "gn_url": v["geonetwork"]["api_url"],
-                "gs_url": v["geoserver"]["url"],
-            }
+            DestinationsResponseElement(
+                name=k,
+                gn_url=v["geonetwork"]["api_url"],
+                gs_url=v["geoserver"]["url"],
+            )
             for k, v in self.config["destinations"].items()
         ]
 

backend/maelstro/core/clone.py

@@ -9,6 +9,7 @@
 from maelstro.metadata import Meta
 from maelstro.config import app_config as config
 from maelstro.common.types import GsLayer
+from maelstro.common.models import PreviewClone
 from .georchestra import GeorchestraHandler, get_georchestra_handler
 from .exceptions import ParamError, MaelstroDetail
 from .operations import raise_for_status
@@ -52,7 +53,7 @@ def copy_preview(
         copy_meta: bool,
         copy_layers: bool,
         copy_styles: bool,
-    ) -> dict[str, list[dict[str, Any]]]:
+    ) -> PreviewClone:
         self.copy_meta = copy_meta
         self.copy_layers = copy_layers
         self.copy_styles = copy_styles
@@ -64,8 +65,8 @@ def copy_preview(
             self.meta = Meta(zipdata)
 
             preview: dict[str, list[dict[str, Any]]] = {
-                "metadata": [],
-                "data": [],
+                "geonetwork_resources": [],
+                "geoserver_resources": [],
             }
 
             src_gn_info = self.geo_hnd.get_service_info(
@@ -77,14 +78,15 @@ def copy_preview(
             )
             dst_gn_url = dst_gn_info["url"]
 
-            preview["metadata"].append(
+            preview["geonetwork_resources"].append(
                 {
                     "src": src_gn_url,
                     "dst": dst_gn_url,
                     "metadata": (
                         [
                             {
                                 "title": self.meta.get_title(),
+                                "iso_standard": self.meta.schema,
                             }
                         ]
                         if self.copy_meta
@@ -113,7 +115,7 @@ def copy_preview(
                     for layer in layers.values():
                         styles.update(self.get_styles_from_layer(layer).keys())
 
-                preview["data"].append(
+                preview["geoserver_resources"].append(
                     {
                         "src": server_url,
                         "dst": dst_gs_url,
@@ -126,7 +128,7 @@ def copy_preview(
                     }
                 )
 
-        return preview
+        return PreviewClone(**preview)  # type: ignore
 
     def clone_dataset(
         self,

backend/maelstro/logging/psql_logger.py

@@ -19,6 +19,7 @@
 from pydantic import TypeAdapter
 from maelstro.config import app_config as config
 from maelstro.common.types import DbConfig
+from maelstro.common.models import JsonLogRecord
 
 
 class DbNotSetup(Exception):
@@ -110,12 +111,12 @@ def log_to_db(record: dict[str, Any]) -> None:
 
 def get_raw_logs(
     size: int, offset: int, get_details: bool = False
-) -> list[dict[str, Any]]:
+) -> list[JsonLogRecord]:
     if not LOGGING_ACTIVE:
         raise DbNotSetup
     with Session(get_engine()) as session:
         return [
-            row.to_dict(get_details)
+            JsonLogRecord(**row.to_dict(get_details))
             for row in session.query(Log)
             .order_by(Log.id.desc())
             .offset(offset)