feat (#1168): allow include regular router to FastAPI integration (#1747

)

* feat (#1168): allow include regular router to FastAPI integration

* docs: generate API References

* docs: update FastAPI integration to use BrokerRouter

* tests: add FastAPI include regular router testcase

---------

Co-authored-by: Lancetnik <Lancetnik@users.noreply.github.com>

docs/docs/en/getting-started/integrations/fastapi/index.md

@@ -89,23 +89,8 @@ To test your **FastAPI StreamRouter**, you can still use it with the *TestClient
 
 ## Multiple Routers
 
-Using **FastStream** as a **FastAPI** plugin you are still able to separate messages processing logic between different routers (like with a regular `HTTPRouter`). But it can be confusing - how you should include multiple routers, if we have to setup `router.lifespan_context` as a **FastAPI** object lifespan.
+Using **FastStream** as a **FastAPI** plugin you are still able to separate messages processing logic between different routers (like with a regular `HTTPRouter`). But it can be confusing - **StreamRouter** patches a **FastAPI** object lifespan.
 
-You can make it in a two ways, depends on you reminds.
+Fortunately, you can use regular **FastStream** routers and include them to the **FastAPI** integration one like in the regular broker object. Also, it can be helpful to reuse your endpoints between **FastAPI** integration and regular **FastStream** app.
 
-### Routers nesting
-
-If you want to use the **SAME CONNECTION** for all of you routers you should nest them each other and finally use only the core router to include it into **FastAPI** object.
-
-{! includes/getting_started/integrations/fastapi/multiple.md !}
-
-This way the core router collects all nested routers publishers and subscribers and stores it like its own.
-
-### Custom lifespan
-
-Otherwise, if you want to has multiple connections to different broker instances, you can just include them separately to the app (each router has own broker and connection in this case)
-
-{! includes/getting_started/integrations/fastapi/multiple_lifespan.md !}
-
-!!! warning
-    This way you lose AsyncAPI schema, but we are working on it.
+{! includes/getting_started/integrations/fastapi/routers.md !}

docs/docs_src/integrations/fastapi/kafka/multiple.py → docs/docs_src/integrations/fastapi/confluent/router.py

@@ -1,7 +1,8 @@
 from fastapi import FastAPI
-from faststream.kafka.fastapi import KafkaRouter
+from faststream.confluent import KafkaRouter
+from faststream.confluent.fastapi import KafkaRouter as StreamRouter
 
-core_router = KafkaRouter()
+core_router = StreamRouter()
 nested_router = KafkaRouter()
 
 @core_router.subscriber("core-topic")

docs/docs_src/integrations/fastapi/confluent/multiple.py → docs/docs_src/integrations/fastapi/kafka/router.py

@@ -1,7 +1,8 @@
 from fastapi import FastAPI
-from faststream.confluent.fastapi import KafkaRouter
+from faststream.kafka import KafkaRouter
+from faststream.kafka.fastapi import KafkaRouter as StreamRouter
 
-core_router = KafkaRouter()
+core_router = StreamRouter()
 nested_router = KafkaRouter()
 
 @core_router.subscriber("core-topic")

docs/docs_src/integrations/fastapi/nats/multiple.py → docs/docs_src/integrations/fastapi/nats/router.py

@@ -1,7 +1,8 @@
 from fastapi import FastAPI
-from faststream.nats.fastapi import NatsRouter
+from faststream.nats import NatsRouter
+from faststream.nats.fastapi import NatsRouter as StreamRouter
 
-core_router = NatsRouter()
+core_router = StreamRouter()
 nested_router = NatsRouter()
 
 @core_router.subscriber("core-subject")

docs/docs_src/integrations/fastapi/rabbit/multiple.py → docs/docs_src/integrations/fastapi/rabbit/router.py

@@ -1,7 +1,8 @@
 from fastapi import FastAPI
-from faststream.rabbit.fastapi import RabbitRouter
+from faststream.rabbit import RabbitRouter
+from faststream.rabbit.fastapi import RabbitRouter as StreamRouter
 
-core_router = RabbitRouter()
+core_router = StreamRouter()
 nested_router = RabbitRouter()
 
 @core_router.subscriber("core-queue")

docs/docs_src/integrations/fastapi/redis/multiple.py → docs/docs_src/integrations/fastapi/redis/router.py

@@ -1,7 +1,8 @@
 from fastapi import FastAPI
-from faststream.redis.fastapi import RedisRouter
+from faststream.redis import RedisRouter
+from faststream.redis.fastapi import RedisRouter as StreamRouter
 
-core_router = RedisRouter()
+core_router = StreamRouter()
 nested_router = RedisRouter()
 
 @core_router.subscriber("core-channel")

docs/includes/getting_started/integrations/fastapi/routers.md

@@ -0,0 +1,29 @@
+=== "AIOKafka"
+
+    ```python linenums="1" hl_lines="2-3 6 12-14 16"
+    {!> docs_src/integrations/fastapi/kafka/router.py !}
+    ```
+
+=== "Confluent"
+
+    ```python linenums="1" hl_lines="2-3 6 12-14 16"
+    {!> docs_src/integrations/fastapi/confluent/router.py !}
+    ```
+
+=== "RabbitMQ"
+
+    ```python linenums="1" hl_lines="2-3 6 12-14 16"
+    {!> docs_src/integrations/fastapi/rabbit/router.py !}
+    ```
+
+=== "NATS"
+
+    ```python linenums="1" hl_lines="2-3 6 12-14 16"
+    {!> docs_src/integrations/fastapi/nats/router.py !}
+    ```
+
+=== "Redis"
+
+    ```python linenums="1" hl_lines="2-3 6 12-14 16"
+    {!> docs_src/integrations/fastapi/redis/router.py !}
+    ```

faststream/broker/fastapi/router.py

@@ -35,6 +35,7 @@
 from faststream.broker.fastapi.get_dependant import get_fastapi_dependant
 from faststream.broker.fastapi.route import wrap_callable_to_fastapi_compatible
 from faststream.broker.middlewares import BaseMiddleware
+from faststream.broker.router import BrokerRouter
 from faststream.broker.types import (
     MsgType,
     P_HandlerParams,
@@ -479,9 +480,9 @@ def serve_asyncapi_schema(
         docs_router.get(f"{schema_url}.yaml")(download_app_yaml_schema)
         return docs_router
 
-    def include_router(
+    def include_router(  # type: ignore[override]
         self,
-        router: "APIRouter",
+        router: Union["StreamRouter[MsgType]", "BrokerRouter[MsgType]"],
         *,
         prefix: str = "",
         tags: Optional[List[Union[str, Enum]]] = None,
@@ -496,6 +497,24 @@ def include_router(
         ),
     ) -> None:
         """Includes a router in the API."""
+        if isinstance(router, BrokerRouter):
+            for sub in router._subscribers.values():
+                sub._call_decorators = (  # type: ignore[attr-defined]
+                    self._add_api_mq_route(
+                        dependencies=(),
+                        response_model=Default(None),
+                        response_model_include=None,
+                        response_model_exclude=None,
+                        response_model_by_alias=True,
+                        response_model_exclude_unset=False,
+                        response_model_exclude_defaults=False,
+                        response_model_exclude_none=False,
+                    ),
+                )
+
+            self.broker.include_router(router)
+            return
+
         if isinstance(router, StreamRouter):  # pragma: no branch
             router.lifespan_context = fake_context
             self.broker.include_router(router.broker)