add openapi parameters for tile dependencies in WMTS endpoints (#1349)

* add openapi parameters for tile dependencies in WMTS endpoints

* fix

* add plans

* update mosaic extension

* change; reduce calls to crs methods

Author: vincentsarago

CHANGES.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+### titiler.extensions
+
+* add: tile's endpoint parameters to the OpenAPI documentation for WMTS extension
+* change: internal of the WMTS extension to increase performance
+
+### titiler.mosaic
+
+* add: tile's endpoint parameters to the OpenAPI documentation for WMTS extension
+* change: internal of the WMTS extension to increase performance
+
 ## 2.0.0 (2026-03-16)
 
 ### Misc

plans/openapi-params-from-dependencies.prompt.md

@@ -0,0 +1,84 @@
+# OpenAPI schema from FastAPI dependencies
+
+## Problem
+
+In the WMTS extension, we construct an endpoint which can accept query-parameter or use `render` configuration to inject them as tile layers. Because the tile's dependencies are not part of the endpoint function signature, so FastAPI won't include them in the OpenAPI schema automatically. This means they won't be documented in the interactive API docs or available for client code generation.
+
+We then need to manually extract the query parameter definitions from a set of dependencies and add them to the OpenAPI schema for the endpoint.
+
+See issue [#1345](https://github.com/developmentseed/titiler/issues/1345)
+
+## Utility function
+
+Add to your utils module:
+
+```python
+from fastapi._compat import get_definitions, get_flat_models_from_fields, get_model_name_map
+from fastapi.dependencies.models import Dependant
+from fastapi.dependencies.utils import get_dependant, get_flat_params
+from fastapi.openapi.utils import _get_openapi_operation_parameters
+
+def dependencies_to_openapi_params(
+    dependencies: list[Callable],
+) -> list[dict[str, Any]]:
+    """Extract OpenAPI query parameter schemas from a list of FastAPI dependencies."""
+    all_fields = []
+    seen: set[str] = set()
+    for dep in dependencies:
+        dependant = get_dependant(path="", call=dep)
+        for field in get_flat_params(dependant):
+            if field.name not in seen:
+                seen.add(field.name)
+                all_fields.append(field)
+
+    if not all_fields:
+        return []
+
+    flat_models = get_flat_models_from_fields(all_fields, known_models=set())
+    model_name_map = get_model_name_map(flat_models)
+    field_mapping, _ = get_definitions(fields=all_fields, model_name_map=model_name_map)
+
+    combined = Dependant(path="")
+    combined.query_params = all_fields
+    return _get_openapi_operation_parameters(
+        dependant=combined,
+        model_name_map=model_name_map,
+        field_mapping=field_mapping,
+    )
+```
+
+## Usage in a route
+
+Pass the result to `openapi_extra` in the route decorator:
+
+```python
+@router.get(
+    "/some-endpoint",
+    openapi_extra={
+        "parameters": dependencies_to_openapi_params(my_dependencies),
+    },
+)
+def my_endpoint(...):
+    ...
+```
+
+## Implementation plan
+
+1. **Add utility to `titiler/core/titiler/core/utils.py`**
+   - Add imports: `get_definitions`, `get_flat_models_from_fields`, `get_model_name_map` from `fastapi._compat`; `Dependant` from `fastapi.dependencies.models`; `get_flat_params` from `fastapi.dependencies.utils`; `_get_openapi_operation_parameters` from `fastapi.openapi.utils`
+   - Add the `dependencies_to_openapi_params` function (see above)
+   - Export it from `titiler.core.utils`
+
+2. **Use in the extension route** (e.g. `titiler/extensions/titiler/extensions/wmts.py`)
+   - Import `dependencies_to_openapi_params` from `titiler.core.utils`
+   - Before registering the route, build the list of `tile_dependencies`
+   - Pass `"parameters": dependencies_to_openapi_params(tile_dependencies)` to `openapi_extra` on the `@router.get(...)` decorator
+
+3. **Tests**
+   - In `titiler/core/tests/test_utils.py`: add `test_dependencies_to_openapi_params` covering empty list, single dep, multiple deps merged, `required` flag, and deduplication
+
+## Notes
+
+- Parameters are deduplicated by name across all dependencies.
+- `required`, `schema`, and `description` are derived from the `Query(...)` annotations on each dependency.
+- This uses FastAPI internals (`_get_openapi_operation_parameters`, `_compat`) — tested against FastAPI 0.135+.

src/titiler/core/tests/test_utils.py

@@ -1,12 +1,16 @@
 """Test utils."""
 
+from typing import Annotated
+
 import pytest
+from fastapi import Query
 
 from titiler.core.dependencies import AssetsExprParams, BidxParams
 from titiler.core.resources.enums import MediaType
 from titiler.core.utils import (
     accept_media_type,
     check_query_params,
+    dependencies_to_openapi_params,
     deserialize_query_params,
     extract_query_params,
     get_dependency_query_params,
@@ -107,6 +111,41 @@ def test_extract_query_params():
     assert len(err) == 0
 
 
+def test_dependencies_to_openapi_params():
+    """Test dependencies_to_openapi_params.
+
+    This Code was generated with help of Claude 2.0. See plans/openapi-params-from-dependencies.prompt.md.
+    """
+
+    # empty list → no params
+    assert dependencies_to_openapi_params([]) == []
+
+    # single dependency
+    params = dependencies_to_openapi_params([BidxParams])
+    names = [p["name"] for p in params]
+    assert names == ["bidx"]
+    assert all(p["in"] == "query" for p in params)
+    assert params[0]["required"] is False
+
+    # multiple dependencies are merged
+    params = dependencies_to_openapi_params([BidxParams, AssetsExprParams])
+    names = [p["name"] for p in params]
+    assert "bidx" in names
+    assert "assets" in names
+    assert "expression" in names
+
+    # required flag is respected
+    assets_param = next(p for p in params if p["name"] == "assets")
+    assert assets_param["required"] is True
+
+    # duplicate params across dependencies are deduplicated
+    def dep_a(scale: Annotated[float | None, Query()] = None): ...
+    def dep_b(scale: Annotated[float | None, Query()] = None): ...
+
+    params = dependencies_to_openapi_params([dep_a, dep_b])
+    assert len([p for p in params if p["name"] == "scale"]) == 1
+
+
 def test_check_query_params():
     """Test check_query_params."""
     # invalid bidx value

src/titiler/core/titiler/core/utils.py

@@ -12,8 +12,19 @@
 import pyproj
 import rasterio
 from fastapi import FastAPI
+from fastapi._compat import (
+    get_definitions,
+    get_flat_models_from_fields,
+    get_model_name_map,
+)
 from fastapi.datastructures import QueryParams
-from fastapi.dependencies.utils import get_dependant, request_params_to_args
+from fastapi.dependencies.models import Dependant
+from fastapi.dependencies.utils import (
+    get_dependant,
+    get_flat_params,
+    request_params_to_args,
+)
+from fastapi.openapi.utils import _get_openapi_operation_parameters
 from geojson_pydantic.geometries import MultiPolygon, Polygon
 from morecantile import TileMatrixSet
 from rasterio.dtypes import dtype_ranges
@@ -250,6 +261,38 @@ def check_query_params(
     return True
 
 
+def dependencies_to_openapi_params(
+    dependencies: list[Callable],
+) -> list[dict[str, Any]]:
+    """Extract OpenAPI query parameter schemas from a list of FastAPI dependencies.
+
+    This Code was generated with help of Claude 2.0. See plans/openapi-params-from-dependencies.prompt.md.
+    """
+    all_fields = []
+    seen: set[str] = set()
+    for dep in dependencies:
+        dependant = get_dependant(path="", call=dep)
+        for field in get_flat_params(dependant):
+            if field.name not in seen:
+                seen.add(field.name)
+                all_fields.append(field)
+
+    if not all_fields:
+        return []
+
+    flat_models = get_flat_models_from_fields(all_fields, known_models=set())
+    model_name_map = get_model_name_map(flat_models)
+    field_mapping, _ = get_definitions(fields=all_fields, model_name_map=model_name_map)
+
+    combined = Dependant(path="")
+    combined.query_params = all_fields
+    return _get_openapi_operation_parameters(
+        dependant=combined,
+        model_name_map=model_name_map,
+        field_mapping=field_mapping,
+    )
+
+
 def accept_media_type(accept: str, mediatypes: list[MediaType]) -> MediaType | None:
     """Return MediaType based on accept header and available mediatype.