Addressing Ran's feedback

Author: leandrodamascena

aws_lambda_powertools/event_handler/openapi/merge.py

@@ -7,6 +7,7 @@
 import importlib.util
 import logging
 import sys
+import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal
 
@@ -232,7 +233,13 @@ def _load_resolver_with_dependencies(
                 _load_module(dep_file, dep_module_name)
                 logger.debug(f"Loaded dependent file: {dep_file}")
             except Exception as e:
-                logger.warning(f"Failed to load dependent file {dep_file}: {e}")
+                warnings.warn(
+                    f"Failed to load dependent file {dep_file}: {e}. "
+                    "If your handler module has side effects at import time "
+                    "(e.g. environment variable validation, database connections), "
+                    "consider deferring them to runtime.",
+                    stacklevel=2,
+                )
 
         # Now get the resolver - it should already be loaded by the dependent files
         # Try to get it from the module that was loaded by dependents
@@ -409,9 +416,25 @@ def get_openapi_schema(self) -> dict[str, Any]:
                 if hasattr(resolver, "get_openapi_schema"):
                     self._schemas.append(_model_to_dict(resolver.get_openapi_schema()))
             except (ImportError, AttributeError, FileNotFoundError) as e:
-                logger.warning(f"Failed to load resolver from {file_path}: {e}")
+                warnings.warn(
+                    f"Failed to load resolver from {file_path}: {e}. "
+                    "If your handler module has side effects at import time "
+                    "(e.g. environment variable validation, database connections), "
+                    "consider deferring them to runtime.",
+                    stacklevel=1,
+                )
 
         self._cached_schema = self._merge_schemas()
+
+        if self._discovered_files and not self._cached_schema.get("paths"):
+            warnings.warn(
+                f"OpenAPIMerge discovered {len(self._discovered_files)} handler file(s) "
+                "but the final schema has no paths. "
+                "Check if your handler modules have side effects at import time "
+                "that prevent route registration.",
+                stacklevel=1,
+            )
+
         return self._cached_schema
 
     def get_openapi_json_schema(self) -> str:

docs/core/event_handler/openapi.md

@@ -61,9 +61,6 @@ The Swagger UI appears by default at the `/swagger` path, but you can customize
 
 ## Customization
 
-???+ warning "OpenAPI schema version depends on the installed version of Pydantic"
-    Pydantic v1 generates [valid OpenAPI 3.0.3 schemas](https://docs.pydantic.dev/1.10/usage/schema/){target="_blank" rel="nofollow"}, and Pydantic v2 generates [valid OpenAPI 3.1.0 schemas](https://docs.pydantic.dev/latest/why/#json-schema){target="_blank" rel="nofollow"}.
-
 ### Customizing parameters
 
 --8<-- "docs/core/event_handler/_openapi_customization_parameters.md"
@@ -185,6 +182,11 @@ OpenAPI Merge uses AST (Abstract Syntax Tree) analysis to detect resolver instan
 * No security concerns from arbitrary code execution
 * Fast discovery across many files
 
+???+ warning "Handler modules must be side-effect-free at import time"
+    While discovery uses static analysis (AST), **schema generation requires importing your handler modules** to extract route definitions. If a handler module runs code at import time - such as validating environment variables, opening database connections, or calling external services — the import will fail silently and its routes will be missing from the final schema.
+
+    If your schema is unexpectedly empty, check whether your handler files have decorators or top-level code that depends on runtime state. Move these to the handler function body or guard them with `if __name__ == "__main__"`.
+
 ### Discovery parameters
 
 The `discover()` method accepts the following parameters: