update swagger documentation

Author: mcucchi9

cads_processing_api_service/auth.py

@@ -40,7 +40,7 @@ def get_auth_header(pat: str | None = None, jwt: str | None = None) -> tuple[str
     Parameters
     ----------
     pat : str | None, optional
-        Personal Access Token
+        API Token
     jwt : str | None, optional
         JSON Web Token
 
@@ -125,10 +125,13 @@ def authenticate_user(
 
 def get_auth_info(
     pat: str | None = fastapi.Header(
-        None, description="Personal Access Token", alias="PRIVATE-TOKEN"
+        None, description="API Token.", alias="PRIVATE-TOKEN"
     ),
     jwt: str | None = fastapi.Header(
-        None, description="JSON Web Token", alias="Authorization"
+        None,
+        description="JSON Web Token",
+        alias="Authorization",
+        include_in_schema=False,
     ),
     portal_header: str | None = fastapi.Header(
         None, alias=SETTINGS.portal_header_name, include_in_schema=False
@@ -139,7 +142,7 @@ def get_auth_info(
     Parameters
     ----------
     pat : str | None, optional
-        Personal Access Token
+        API Token
     jwt : str | None, optional
         JSON Web Token
     portal_header : str | None, optional

cads_processing_api_service/clients.py

@@ -86,9 +86,12 @@ class DatabaseClient(ogc_api_processes_fastapi.clients.BaseClient):
     @exceptions.exception_logger
     def get_processes(
         self,
-        limit: int | None = fastapi.Query(10, ge=1, le=10000),
+        limit: int | None = fastapi.Query(
+            10, ge=1, le=10000, description="Maximum number of results to return."
+        ),
         sortby: utils.ProcessSortCriterion | None = fastapi.Query(
-            utils.ProcessSortCriterion.resource_uid_asc
+            utils.ProcessSortCriterion.resource_uid_asc,
+            description="Sorting criterion.",
         ),
         cursor: str | None = fastapi.Query(None, include_in_schema=False),
         back: bool | None = fastapi.Query(None, include_in_schema=False),
@@ -148,7 +151,7 @@ def get_processes(
     def get_process(
         self,
         response: fastapi.Response,
-        process_id: str = fastapi.Path(...),
+        process_id: str = fastapi.Path(..., description="Process identifier."),
         portals: tuple[str] | None = fastapi.Depends(utils.get_portals),
     ) -> ogc_api_processes_fastapi.models.ProcessDescription:
         """Implement OGC API - Processes `GET /processes/{process_id}` endpoint.
@@ -201,7 +204,7 @@ def get_process(
     def post_process_execution(
         self,
         request: fastapi.Request,
-        process_id: str = fastapi.Path(...),
+        process_id: str = fastapi.Path(..., description="Process identifier."),
         execution_content: models.Execute = fastapi.Body(...),
         auth_info: models.AuthInfo = fastapi.Depends(auth.get_auth_info),
     ) -> models.StatusInfo:
@@ -330,18 +333,30 @@ def post_process_execution(
     @exceptions.exception_logger
     def get_jobs(
         self,
-        processID: list[str] | None = fastapi.Query(None),
+        processID: list[str] | None = fastapi.Query(
+            None,
+            description=(
+                "Processes identifiers. Only jobs associated to the specified "
+                "processes shall be included in the response."
+            ),
+        ),
         status: list[models.StatusCode] | None = fastapi.Query(
             [
                 ogc_api_processes_fastapi.models.StatusCode.accepted,
                 ogc_api_processes_fastapi.models.StatusCode.running,
                 ogc_api_processes_fastapi.models.StatusCode.successful,
                 ogc_api_processes_fastapi.models.StatusCode.failed,
-            ]
+            ],
+            description=(
+                "Job statuses. Only jobs with the specified statuses shall be included in "
+                "the response."
+            ),
+        ),
+        limit: int | None = fastapi.Query(
+            10, ge=1, le=10000, description="Maximum number of results to return."
         ),
-        limit: int | None = fastapi.Query(10, ge=1, le=10000),
         sortby: utils.JobSortCriterion | None = fastapi.Query(
-            utils.JobSortCriterion.created_at_desc
+            utils.JobSortCriterion.created_at_desc, description="Sorting criterion."
         ),
         cursor: str | None = fastapi.Query(None, include_in_schema=False),
         back: bool | None = fastapi.Query(None, include_in_schema=False),
@@ -459,12 +474,21 @@ def get_jobs(
     @exceptions.exception_logger
     def get_job(
         self,
-        job_id: str = fastapi.Path(...),
-        qos: bool = fastapi.Query(False),
-        request: bool = fastapi.Query(False),
-        log: bool = fastapi.Query(False),
+        job_id: str = fastapi.Path(..., description="Job identifier."),
+        qos: bool = fastapi.Query(
+            False, description="Whether to include job qos info in the response."
+        ),
+        request: bool = fastapi.Query(
+            False,
+            description="Whether to include the sumbitted request in the response.",
+        ),
+        log: bool = fastapi.Query(
+            False, description="Whether to include the job's log in the response."
+        ),
         log_start_time: datetime.datetime | None = fastapi.Query(
-            None, alias="logStartTime"
+            None,
+            alias="logStartTime",
+            description="Datetime of the first log message to be returned.",
         ),
         auth_info: models.AuthInfo = fastapi.Depends(auth.get_auth_info),
     ) -> models.StatusInfo:
@@ -589,7 +613,7 @@ def get_job(
     @exceptions.exception_logger
     def get_job_results(
         self,
-        job_id: str = fastapi.Path(...),
+        job_id: str = fastapi.Path(..., description="Job identifier."),
         auth_info: models.AuthInfo = fastapi.Depends(auth.get_auth_info),
     ) -> ogc_api_processes_fastapi.models.Results:
         """Implement OGC API - Processes `GET /jobs/{job_id}/results` endpoint.
@@ -652,7 +676,7 @@ def get_job_results(
     @exceptions.exception_logger
     def delete_job(
         self,
-        job_id: str = fastapi.Path(...),
+        job_id: str = fastapi.Path(..., description="Job identifier."),
         auth_info: models.AuthInfo = fastapi.Depends(auth.get_auth_info),
     ) -> ogc_api_processes_fastapi.models.StatusInfo:
         """Implement OGC API - Processes `DELETE /jobs/{job_id}` endpoint.

cads_processing_api_service/config.py

@@ -35,7 +35,12 @@
 API_DESCRIPTION = (
     "This REST API service enables the submission of processing tasks (data retrieval) to the "
     "CADS system, and their consequent monitoring and management. "
-    "The service is based on the [OGC API - Processes standard](https://ogcapi.ogc.org/processes/)."
+    "The service is based on the [OGC API - Processes standard](https://ogcapi.ogc.org/processes/).\n\n"
+    "Being based on the OGC API - Processes standard, some terminology is inherited from it. "
+    "In the context of this specific API, each _process_ is associated with a specific dataset "
+    "and enables the retrieval of data from that dataset: as such, each _process_ identifier "
+    "corresponds to a specific dataset identifier.\n"
+    "A _job_, instead, is a specific data retrieval task that has been submitted for execution."
 )
 
 API_REQUEST_TEMPLATE = """import cdsapi

cads_processing_api_service/constraints.py

@@ -11,7 +11,7 @@
 
 @exceptions.exception_logger
 def apply_constraints(
-    process_id: str = fastapi.Path(...),
+    process_id: str = fastapi.Path(..., description="Process identifier."),
     execution_content: models.Execute = fastapi.Body(...),
     portals: tuple[str] | None = fastapi.Depends(utils.get_portals),
 ) -> dict[str, Any]:

cads_processing_api_service/costing.py

@@ -34,7 +34,7 @@ class RequestOrigin(str, enum.Enum):
 
 @exceptions.exception_logger
 def estimate_cost(
-    process_id: str = fastapi.Path(...),
+    process_id: str = fastapi.Path(..., description="Process identifier."),
     request_origin: RequestOrigin = fastapi.Query("api", include_in_schema=False),
     mandatory_inputs: bool = fastapi.Query(False, include_in_schema=False),
     execution_content: models.Execute = fastapi.Body(...),

cads_processing_api_service/translators.py

@@ -337,7 +337,7 @@ def format_api_request(
 
 @exceptions.exception_logger
 def get_api_request(
-    process_id: str = fastapi.Path(...),
+    process_id: str = fastapi.Path(..., description="Process identifier."),
     request: dict[str, Any] = fastapi.Body(...),
 ) -> dict[str, str]:
     """Get CADS API request equivalent to the provided processing request.