[DOP-31720] Improve Swagger field examples

Author: dolfinus

syncmaster/schemas/v1/transfers/db.py

@@ -20,7 +20,11 @@
 
 class DBTransfer(BaseModel):
     TABLE_NAME_PATTERN: ClassVar[str] = r"^[\w\d]+\.[\w\d]+$"
-    table_name: str = Field(description="Table name", json_schema_extra={"pattern": TABLE_NAME_PATTERN})
+    table_name: str = Field(
+        description="Table name",
+        json_schema_extra={"pattern": TABLE_NAME_PATTERN},
+        examples=["myschema.mytable"],
+    )
 
     # make error message more user friendly
     @field_validator("table_name", mode="before")
@@ -60,7 +64,11 @@ class IcebergTransferSourceOrTarget(DBTransfer):
     type: ICEBERG_TYPE
 
     TABLE_NAME_PATTERN: ClassVar[str] = r"^[\w\d]+(\.[\w\d]+)+$"
-    table_name: str = Field(description="Table name", json_schema_extra={"pattern": TABLE_NAME_PATTERN})
+    table_name: str = Field(
+        description="Table name",
+        json_schema_extra={"pattern": TABLE_NAME_PATTERN},
+        examples=["myschema.mytable"],
+    )
 
     # make error message more user friendly
     @field_validator("table_name", mode="before")

syncmaster/schemas/v1/transfers/transformations/dataframe_columns_filter.py

@@ -15,12 +15,12 @@ class IncludeFilter(BaseColumnsFilter):
 
 class RenameFilter(BaseColumnsFilter):
     type: Literal["rename"]
-    to: str
+    to: str = Field(examples=["new_column_name"])
 
 
 class CastFilter(BaseColumnsFilter):
     type: Literal["cast"]
-    as_type: str
+    as_type: str = Field(examples=["int"])
 
 
 ColumnsFilter = IncludeFilter | RenameFilter | CastFilter

syncmaster/schemas/v1/transfers/transformations/dataframe_rows_filter.py

@@ -19,57 +19,57 @@ class IsNotNullFilter(BaseRowsFilter):
 
 class EqualFilter(BaseRowsFilter):
     type: Literal["equal"]
-    value: str
+    value: str = Field(examples=["123"])
 
 
 class NotEqualFilter(BaseRowsFilter):
     type: Literal["not_equal"]
-    value: str
+    value: str = Field(examples=["123"])
 
 
 class GreaterThanFilter(BaseRowsFilter):
     type: Literal["greater_than"]
-    value: str
+    value: str = Field(examples=["123"])
 
 
 class GreaterOrEqualFilter(BaseRowsFilter):
     type: Literal["greater_or_equal"]
-    value: str
+    value: str = Field(examples=["123"])
 
 
 class LessThanFilter(BaseRowsFilter):
     type: Literal["less_than"]
-    value: str
+    value: str = Field(examples=["123"])
 
 
 class LessOrEqualFilter(BaseRowsFilter):
     type: Literal["less_or_equal"]
-    value: str
+    value: str = Field(examples=["123"])
 
 
 class LikeFilter(BaseRowsFilter):
     type: Literal["like"]
-    value: str
+    value: str = Field(examples=["%.json"])
 
 
 class ILikeFilter(BaseRowsFilter):
     type: Literal["ilike"]
-    value: str
+    value: str = Field(examples=["%.json"])
 
 
 class NotLikeFilter(BaseRowsFilter):
     type: Literal["not_like"]
-    value: str
+    value: str = Field(examples=["%.json"])
 
 
 class NotILikeFilter(BaseRowsFilter):
     type: Literal["not_ilike"]
-    value: str
+    value: str = Field(examples=["%.json"])
 
 
 class RegexpFilter(BaseRowsFilter):
     type: Literal["regexp"]
-    value: str
+    value: str = Field(examples=[r"^\d+\.json$"])
 
 
 RowsFilter = (

syncmaster/schemas/v1/transfers/transformations/file_metadata_filter.py

@@ -9,7 +9,7 @@
 
 class NameGlobFilter(BaseModel):
     type: Literal["name_glob"]
-    value: str
+    value: str = Field(examples=["*.json"])
 
     @field_validator("value", mode="before")
     @classmethod
@@ -23,7 +23,7 @@ def _validate_pattern(cls, value: str) -> str:
 
 class NameRegexpFilter(BaseModel):
     type: Literal["name_regexp"]
-    value: str
+    value: str = Field(examples=[r"^\d+\.json$"])
 
     @field_validator("value", mode="before")
     @classmethod
@@ -39,12 +39,12 @@ def _validate_pattern(cls, value: str) -> str:
 
 class FileSizeMinFilter(BaseModel):
     type: Literal["file_size_min"]
-    value: ByteSize
+    value: ByteSize = Field(examples=[1024 * 1024])
 
 
 class FileSizeMaxFilter(BaseModel):
     type: Literal["file_size_max"]
-    value: ByteSize
+    value: ByteSize = Field(examples=[1024 * 1024 * 1024])
 
 
 MetadataFilter = NameGlobFilter | NameRegexpFilter | FileSizeMinFilter | FileSizeMaxFilter

syncmaster/schemas/v1/transfers/transformations/sql.py

@@ -3,15 +3,15 @@
 import re
 from typing import Literal
 
-from pydantic import BaseModel, field_validator
+from pydantic import BaseModel, Field, field_validator
 
 ALLOWED_SELECT_QUERY = re.compile(r"^\s*(SELECT|WITH)\b", re.IGNORECASE)
 
 
 class Sql(BaseModel):
     type: Literal["sql"]
-    query: str
-    dialect: Literal["spark"] = "spark"
+    query: str = Field(examples=["SELECT col1, col2 FROM source WHERE col3 <= 20"])
+    dialect: Literal["spark"] = Field(default="spark", description="Static value for now")
 
     @field_validator("query", mode="after")
     @classmethod