WIP improving API documentation #24

py/API_models/exports.py

@@ -20,12 +20,12 @@ class EMODnetExportRsp(BaseModel):
     """
         EMODNet format export response.
     """
-    errors: List[str] = Field(title="Showstopper problems found while building the archive.",
-                              default=[])
-    warnings: List[str] = Field(title="Problems found while building the archive, which do not prevent producing it.",
-                                default=[])
-    job_id: int = Field(title="The created job, 0 if there were problems.",
-                        default=0)
+    errors: List[str] = Field(title="Errors", description="Showstopper problems found while building the archive.", 
+                                example=[], default=[])
+    warnings: List[str] = Field(title="Warnings", description="Problems found while building the archive, which do not prevent producing it.", 
+                                example=[], default=[])
+    job_id: int = Field(title="Job Id", description="The created job, 0 if there were problems.", 
+                                example=1, default=0)
 
 
 class ExportTypeEnum(str, Enum):

py/API_models/helpers/DataclassToModel.py

@@ -24,7 +24,7 @@ class DataclassConfig(BaseConfig):
 T = TypeVar('T')
 
 
-def dataclass_to_model(clazz: T, add_suffix: bool = False, titles: Optional[Dict[str, str]] = None) -> PydanticModelT:
+def dataclass_to_model(clazz: T, add_suffix: bool = False, titles: Optional[Dict[str, str]] = None, descriptions: Optional[Dict[str, str]] = None ) -> PydanticModelT:
     model_fields = {}
     a_field: dataclasses.Field
     for a_field in dataclasses.fields(clazz):
@@ -61,4 +61,10 @@ def dataclass_to_model(clazz: T, add_suffix: bool = False, titles: Optional[Dict
         for a_field_name, a_title in titles.items():
             the_field: ModelField = ret.__fields__[a_field_name]
             the_field.field_info.title = a_title
+    if descriptions is not None:
+        # Amend with descriptions, for doc. Let crash (KeyError) if descriptions are not up-to-date with base.
+        for a_field_name, a_description in descriptions.items():
+            the_field: ModelField = ret.__fields__[a_field_name]
+            the_field.field_info.description = a_description
+
     return ret

py/API_models/login.py

@@ -9,5 +9,6 @@
 
 
 class LoginReq(BaseModel):
-    username: str = Field("User email, like in Web UI")
-    password: str = Field("User password")
+    password: str = Field(title="User's password" , default=None, description="User password", example="UserPassword!")
+    username: str = Field(title="User's eamil", default=None, description="User email used during registration", example="[email protected]")
+

py/API_models/merge.py

@@ -15,5 +15,5 @@
 
 class MergeRsp(BaseModel):
     """ Merge response. """
-    errors: List[str] = Field(title="The errors found during processing.",
+    errors: List[str] = Field(title="Errors", description="The errors found during processing.",
                               default=[])

py/API_models/subset.py

@@ -21,16 +21,16 @@ class GroupDefinitions(str, Enum):
 
 class SubsetReq(BaseModel):
     """ Subset request. """
-    filters: Dict[str, str] = Field(title="The filters to apply to project", default={})
-    dest_prj_id: int = Field(title="The destination project ID.")
-    group_type: GroupDefinitions = Field(title="Define the groups in which to apply limits. C for categories, S for samples, A for acquisitions.")
-    limit_type: LimitMethods = Field(title="The type of limit_value: P for %, V for constant, both per group.")
-    limit_value: float = Field(title="Limit value, e.g. 20% or 5 per copepoda or 5% per sample.")
-    do_images: bool = Field(title="If set, also clone images.")
+    filters: Dict[str, str] = Field(title="Filters", description="The filters to apply to project", default={}, example={"freenum": "n01", "freenumst": "0"})
+    dest_prj_id: int = Field(title="Destination project id", description="The destination project ID.", example=22)
+    group_type: GroupDefinitions = Field(title="Group type", description="Define the groups in which to apply limits. C for categories, S for samples, A for acquisitions.", example=GroupDefinitions.acquisitions)
+    limit_type: LimitMethods = Field(title="Limit type", description="The type of limit_value: P for %, V for constant, both per group.", example=LimitMethods.percent)
+    limit_value: float = Field(title="Limit value", description="Limit value, e.g. 20% or 5 per copepoda or 5% per sample.", example=10.0)
+    do_images: bool = Field(title="Do images", description="If set, also clone images.", example=True)
 
 
 class SubsetRsp(BaseModel):
     """ Subset response. """
-    job_id: int = Field(title="The job created for this operation.")
+    job_id: int = Field(title="Job Id", description="The job created for this operation.",example=143)
     # errors: List[str] = Field(title="The errors found during processing",
     #                           default=[])