docs: compare native FunctionApp tooling with FastAPI ASGI hosting

PRD.md

@@ -8,6 +8,12 @@ Azure Functions Python v2 programming model.
 It is intended for decorator-based `func.FunctionApp()` applications that want lightweight API
 documentation without adopting a full web framework.
 
+FastAPI hosted through Azure Functions `AsgiFunctionApp` is a supported alternative
+architecture, not a missing platform feature. Existing FastAPI applications should
+normally retain their own routing, dependency injection, validation and OpenAPI
+generation. This package targets native FunctionApp handlers and does not generate
+documentation by traversing an ASGI application's internal router.
+
 ## Problem Statement
 
 Azure Functions Python applications often expose HTTP APIs without a consistent way to:

README.md

@@ -19,7 +19,8 @@ OpenAPI (Swagger) documentation and Swagger UI for the **Azure Functions Python
 
 ## Why this exists
 
-Azure Functions Python v2 has no built-in API documentation story:
+Native `func.FunctionApp()` HTTP handlers do not automatically get OpenAPI
+documentation from the Azure Functions SDK alone:
 
 - **No auto-generated docs** — you maintain OpenAPI specs by hand or not at all
 - **No Swagger UI** — no browser-based API explorer for testing endpoints
@@ -109,13 +110,32 @@ flowchart LR
 
 ## FastAPI comparison
 
-| Feature | FastAPI | azure-functions-openapi |
-|---------|---------|------------------------|
-| API docs generation | Built-in from type hints | `@openapi` decorator on handlers |
-| Swagger UI | `/docs` auto-served | `render_swagger_ui()` endpoint |
-| OpenAPI spec | Auto-generated `/openapi.json` | `get_openapi_json()` endpoint |
-| CLI spec export | N/A | `azure-functions-openapi generate` |
-| Pydantic integration | Native | `requests=` / `responses=` |
+**FastAPI also runs on Azure Functions.** The choice is the HTTP programming
+model, not whether Azure Functions supports a web framework. See the official
+[FastAPI on Azure Functions sample](https://github.com/Azure-Samples/fastapi-on-azure-functions)
+(archived reference) and the current
+[`AsgiFunctionApp` API](https://learn.microsoft.com/en-us/python/api/azure-functions/azure.functions.asgifunctionapp).
+
+| Concern | Native `FunctionApp` + this package | FastAPI on `AsgiFunctionApp` |
+|---------|------------------------------------|-----------------------------|
+| HTTP routing | Azure `@app.route` handlers | FastAPI path operations behind the ASGI adapter |
+| Documentation | `@openapi` metadata; explicitly register spec/UI routes | FastAPI generates its own OpenAPI and docs routes |
+| Bindings | Keep Azure input/output bindings on native handlers | FastAPI endpoints do not automatically receive native binding arguments; use SDK clients or explicit integration code |
+| Middleware and DI | This package supplies neither ASGI middleware nor dependency injection | Keep FastAPI/Starlette middleware and FastAPI dependencies |
+| Validation | Documentation only; optionally pair with `azure-functions-validation` | FastAPI owns request parsing, validation and response-model serialization |
+| Spec export | `azure-functions-openapi generate` | Export the document returned by the FastAPI app's `openapi()` method |
+
+**When to use:** choose this package when your handlers already use native
+FunctionApp decorators and bindings and you want documentation without replacing
+that model. **When not to use:** keep FastAPI on `AsgiFunctionApp` for an existing
+FastAPI app, or when its middleware, dependency injection and integrated validation
+are the desired application model. This package does not inspect FastAPI's nested
+router or replace its OpenAPI generator. ASGI hosting does not preclude separate
+native functions, but bridging their bindings into FastAPI endpoints is not automatic.
+
+This is the same documentation-versus-runtime-validation boundary described for
+the optional Validation companion below. Neither approach is claimed to have
+lower cold-start or import time; no comparable benchmark is provided here.
 
 ## Scope
 

docs/index.md

@@ -7,6 +7,17 @@
 
 ## Why teams use it
 
+This package targets native `func.FunctionApp()` handlers. For an existing FastAPI
+application, Azure Functions also supports
+[`AsgiFunctionApp`](https://learn.microsoft.com/en-us/python/api/azure-functions/azure.functions.asgifunctionapp):
+keep FastAPI's own routing, middleware, dependency injection and OpenAPI generator.
+Choose the native model when Azure handler bindings are central; FastAPI endpoints
+do not automatically receive native binding arguments. See the
+[official ASGI sample](https://github.com/Azure-Samples/fastapi-on-azure-functions)
+(archived reference) and the [README comparison](https://github.com/yeongseon/azure-functions-openapi-python#fastapi-comparison).
+This library documents contracts; it does not perform runtime validation or claim
+a measured cold-start advantage over ASGI hosting.
+
 - Keep API docs close to function code with `@openapi`
 - Generate OpenAPI 3.0.0, 3.1.0, or 3.2.0 from runtime metadata
 - Serve JSON, YAML, and Swagger UI from the same Function App
@@ -46,7 +57,7 @@ class HelloResponse(BaseModel):
         }
     ],
     responses=HelloResponse,
-    )
+)
 @app.route(route="http_trigger", methods=["GET"], auth_level=func.AuthLevel.ANONYMOUS)
 def http_trigger(req: func.HttpRequest) -> func.HttpResponse:
     name = req.params.get("name", "world")