Improve swagger documentation

cads_processing_api_service/auth.py

@@ -130,7 +130,9 @@ def get_auth_info(
     jwt: str | None = fastapi.Header(
         None, description="JSON Web Token", alias="Authorization"
     ),
-    portal_header: str | None = fastapi.Header(None, alias=SETTINGS.portal_header_name),
+    portal_header: str | None = fastapi.Header(
+        None, alias=SETTINGS.portal_header_name, include_in_schema=False
+    ),
 ) -> models.AuthInfo | None:
     """Get authentication information from the incoming HTTP request.
 

cads_processing_api_service/config.py

@@ -31,6 +31,13 @@
 
 logger: structlog.stdlib.BoundLogger = structlog.get_logger(__name__)
 
+API_TITLE = "CADS Processing API"
+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/)."
+)
+
 API_REQUEST_TEMPLATE = """import cdsapi
 
 dataset = "{process_id}"
@@ -189,6 +196,9 @@ def profiles_api_url(self) -> str:
     cache_resources_maxsize: int = 1000
     cache_resources_ttl: int = 10
 
+    api_title: str = API_TITLE
+    api_description: str = API_DESCRIPTION
+
     api_request_template: str = API_REQUEST_TEMPLATE
     api_request_max_list_length: dict[str, int] = API_REQUEST_MAX_LIST_LENGTH
     missing_dataset_title: str = "Dataset not available"

cads_processing_api_service/costing.py

@@ -35,8 +35,8 @@ class RequestOrigin(str, enum.Enum):
 @exceptions.exception_logger
 def estimate_cost(
     process_id: str = fastapi.Path(...),
-    request_origin: RequestOrigin = fastapi.Query("api"),
-    mandatory_inputs: bool = fastapi.Query(False),
+    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(...),
     portals: tuple[str] | None = fastapi.Depends(utils.get_portals),
 ) -> models.RequestCost:

cads_processing_api_service/main.py

@@ -68,9 +68,12 @@ async def lifespan(application: fastapi.FastAPI) -> AsyncGenerator[Any, None]:
 
 logger = structlog.get_logger(__name__)
 
+
 app = ogc_api_processes_fastapi.instantiate_app(
     client=clients.DatabaseClient(),  # type: ignore
     exception_handler=exceptions.exception_handler,
+    title=SETTINGS.api_title,
+    description=SETTINGS.api_description,
 )
 app = exceptions.include_exception_handlers(app)
 # FIXME : "app.router.lifespan_context" is not officially supported and would likely break
@@ -91,11 +94,13 @@ async def lifespan(application: fastapi.FastAPI) -> AsyncGenerator[Any, None]:
 app.router.add_api_route(
     "/processes/{process_id}/api-request",
     translators.get_api_request,
-    description="Get API request equivalent to the submitted prrocess execution json.",
+    description="Get API request equivalent to the submitted process execution json.",
     methods=["POST"],
 )
 
-app.router.add_api_route("/metrics", starlette_exporter.handle_metrics)
+app.router.add_api_route(
+    "/metrics", starlette_exporter.handle_metrics, include_in_schema=False
+)
 app.add_middleware(middlewares.ProcessingPrometheusMiddleware, group_paths=True)
 
 

cads_processing_api_service/utils.py

@@ -662,7 +662,9 @@ def make_status_info(
 
 
 def get_portals(
-    portal_header: str | None = fastapi.Header(None, alias=SETTINGS.portal_header_name),
+    portal_header: str | None = fastapi.Header(
+        None, alias=SETTINGS.portal_header_name, include_in_schema=False
+    ),
 ) -> tuple[str, ...] | None:
     """Get the list of portals from the incoming HTTP request's header.