Merge pull request #83 from ecmwf-projects/COPDS-2005-openapi-docs-fixes

OpenAPI and docs fixes

cads_catalogue_api_service/config.py

@@ -29,6 +29,9 @@
 class SqlalchemySettings(stac_fastapi.types.config.ApiSettings):  # type: ignore
     """Postgres-specific API settings."""
 
+    openapi_url: str = "/openapi.json"
+    docs_url: str = "/docs"
+
     # Fields which are defined by STAC but not included in the database model
     forbidden_fields: set[str] = {"type"}
 

cads_catalogue_api_service/dependencies.py

@@ -49,7 +49,9 @@ def get_portals_values(portal: str | None) -> list[str] | None:
 
 
 def get_portals(
-    portal=fastapi.Header(default=None, alias=config.PORTAL_HEADER_NAME),
+    portal=fastapi.Header(
+        default=None, alias=config.PORTAL_HEADER_NAME, include_in_schema=False
+    ),
 ) -> list[str] | None:
     """Fastapi dependency that provides the CADS portal profile."""
     portals = get_portals_values(portal)

cads_catalogue_api_service/extensions.py

@@ -35,13 +35,18 @@ class CatalogueSortCriterion(str, enum.Enum):
 def datasets_search(
     request: fastapi.Request,
     q: str = fastapi.Query(default=None, description="Full-text search query"),
-    kw: list[str] | None = fastapi.Query(default=[]),
+    kw: list[str] | None = fastapi.Query(
+        default=[], description="Filter by keyword(s)"
+    ),
     sortby: CatalogueSortCriterion = fastapi.Query(
         default=CatalogueSortCriterion.update_desc
     ),
     page: int = fastapi.Query(default=0, ge=0),
     limit: int = fastapi.Query(default=config.MAX_LIMIT, ge=1, le=config.MAX_LIMIT),
-    search_stats: bool = fastapi.Query(default=True),
+    search_stats: bool = fastapi.Query(
+        default=True,
+        description="Include additional search statistics in results (like: faceted data)",
+    ),
 ) -> dict[str, Any]:
     """Filter datasets based on search parameters."""
     return client.cads_client.all_datasets(

cads_catalogue_api_service/main.py

@@ -90,7 +90,7 @@ async def lifespan(application: fastapi.FastAPI):
 def catalogue_openapi() -> dict[str, Any]:
     """OpenAPI, but with not implemented paths removed."""
     openapi_schema = fastapi.openapi.utils.get_openapi(
-        title="CADS Catalogue", version=api.api_version, routes=api.app.routes
+        title="CADS STAC Catalogue", version=api.api_version, routes=api.app.routes
     )
 
     del openapi_schema["paths"]["/collections/{collection_id}/items"]
@@ -105,6 +105,15 @@ def catalogue_openapi() -> dict[str, Any]:
 app.openapi = catalogue_openapi
 
 
+@app.get("/api.html", include_in_schema=False)
+async def api_html():
+    """Redirect legacy STAC fastapi route to default used by other APIs."""
+    return fastapi.responses.RedirectResponse(
+        url="/api/catalogue/v1/docs",
+        status_code=starlette.status.HTTP_301_MOVED_PERMANENTLY,
+    )
+
+
 @app.exception_handler(exceptions.FeatureNotImplemented)
 async def feature_not_implemented_handler(
     request: fastapi.Request, exc: exceptions.FeatureNotImplemented

cads_catalogue_api_service/schema_org.py

@@ -60,6 +60,7 @@ def get_url_link(collection: stac_fastapi.types.stac.Collection, type: str) -> s
     response_model=models.schema_org.Dataset,
     response_model_by_alias=True,
     response_model_exclude_none=True,
+    include_in_schema=False,
 )
 def schema_org_json_ld(
     collection_id: str,