docs: Improve the documentation page with Response class (#2238)

* Improve docs

* docs: generate API References

* Add information about `NatsResponse` class

* docs: generate API References

* Correct response headers, revert example structure

* Added documentation for other brokers

* docs: generate API References

* docs: polish style and text

---------

Co-authored-by: Nikita Pastukhov <[email protected]>

Author: kondratevdev

docs/docs/en/nats/rpc.md

@@ -23,13 +23,10 @@ Just send a message like a regular one and get a response synchronously.
 
 It is very close to the common **requests** syntax:
 
-```python hl_lines="3"
+```python linenums="1" hl_lines="3"
 from faststream.nats import NatsMessage
 
-msg: NatsMessage = await broker.request(
-    "Hi!",
-    subject="test",
-)
+msg: NatsMessage = await broker.request("Hello, NATS!", subject="test")
 ```
 
 ## Reply-To
@@ -38,7 +35,7 @@ Also, if you want to create a permanent request-reply data flow, probably, you s
 
 So, if you have such one, you can specify it with the `reply_to` argument. This way, **FastStream** will send a response to this subject automatically.
 
-```python hl_lines="1 8"
+```python linenums="1" hl_lines="1 8"
 @broker.subscriber("response-subject")
 async def consume_responses(msg):
     ...
@@ -49,3 +46,89 @@ await broker.publish(
     reply_to="response-subject",
 )
 ```
+
+## Creating an RPC subscriber
+
+To handle an RPC request, you need to create a subscriber that processes the incoming message and returns a response.
+The subscriber should be decorated with `#!python @broker.subscriber` and return either a raw value or a `Response` object.
+
+Below is an example of a simple RPC subscriber that processes a message and returns a response.
+
+```python linenums="1" hl_lines="7"
+from faststream.nats import NatsBroker
+
+broker = NatsBroker()
+
+@broker.subscriber("test")
+async def handle(msg):
+    return f"Received: {msg}"
+```
+
+When the client sends a request like this:
+
+```python linenums="1" hl_lines="3"
+from faststream.nats import NatsMessage
+
+msg: NatsMessage = await broker.request("Hello, NATS!", subject="test")
+assert msg.body == b"Received: Hello, NATS!"
+```
+
+The subscriber processes the request and sends back the response, which is received by the client.
+
+!!! tip
+    You can use the `no_reply=True` flag in the `#!python @broker.subscriber` decorator to suppress automatic RPC and `reply_to` responses.
+    This is useful when you want the subscriber to process the message without sending a response back to the client.
+
+## Using the Response class
+
+The `Response` class allows you to attach metadata, such as headers, to the response message.
+This is useful for adding context or tracking information to your responses.
+
+Below is an example of how to use the `Response` class in an RPC subscriber.
+
+```python linenums="1" hl_lines="1 8-12"
+from faststream import Response
+from faststream.nats import NatsBroker
+
+broker = NatsBroker()
+
+@broker.subscriber("test")
+async def handle(msg):
+    return Response(
+        body=f"Processed: {msg}",
+        headers={"x-token": "some-token"},
+        correlation_id="some-correlation-id",
+    )
+```
+
+When the client sends a request:
+
+```python linenums="1" hl_lines="4-6"
+from faststream.nats import NatsMessage
+
+msg: NatsMessage = await broker.request("Hello, NATS!", subject="test")
+assert msg.body == b"Processed: Hello, NATS!"
+assert msg.headers == {"x-token": "some-token"}
+assert msg.correlation_id == "some-correlation-id"
+```
+
+## Using the NatsResponse class
+
+For NATS-specific use cases, you can use the `NatsResponse` class instead of the generic `Response` class.
+
+The `NatsResponse` class extends `Response` and adds support for specifying a `stream` parameter. This ensures the response is published to the correct stream in a JetStream context.
+
+```python linenums="1" hl_lines="1 7-13"
+from faststream.nats import NatsBroker, NatsResponse
+
+broker = NatsBroker()
+
+@broker.subscriber("test", stream="stream")
+async def handle(msg):
+    return NatsResponse(
+        body=f"Processed: {msg}",
+        headers={"x-token": "some-token"},
+        correlation_id="some-correlation-id",
+        stream="stream",
+    )
+```

docs/docs/en/rabbit/rpc.md

@@ -20,13 +20,10 @@ Just send a message like a regular one and get a response synchronously.
 
 It is very close to common **requests** syntax:
 
-```python hl_lines="3"
+```python linenums="1" hl_lines="3"
 from faststream.rabbit import RabbitMessage
 
-msg: RabbitMessage = await broker.request(
-    "Hi!",
-    queue="test",
-)
+msg: RabbitMessage = await broker.request("Hello, RabbitMQ!", queue="test")
 ```
 
 ## Reply-To
@@ -35,14 +32,106 @@ Also, if you want to create a permanent request-reply data flow, probably, you s
 
 So, if you have such one, you can specify it with the `reply_to` argument. This way, **FastStream** will send a response to this queue automatically.
 
-```python hl_lines="1 8"
+```python linenums="1" hl_lines="1 8"
 @broker.subscriber("response-queue")
 async def consume_responses(msg):
     ...
 
 await broker.publish(
-    "Hi!",
+    "Hello, RabbitMQ!",
     queue="test",
     reply_to="response-queue",
 )
 ```
+
+## Creating an RPC subscriber
+
+To handle an RPC request, you need to create a subscriber that processes the incoming message and returns a response.
+The subscriber should be decorated with `#!python @broker.subscriber` and return either a raw value or a `Response` object.
+
+Below is an example of a simple RPC subscriber that processes a message and returns a response.
+
+```python linenums="1" hl_lines="7"
+from faststream.rabbit import RabbitBroker
+
+broker = RabbitBroker()
+
+@broker.subscriber("test")
+async def handle(msg):
+    return f"Received: {msg}"
+```
+
+When the client sends a request like this:
+
+```python linenums="1" hl_lines="3"
+from faststream.rabbit import RabbitMessage
+
+msg: RabbitMessage = await broker.request("Hello, RabbitMQ!", queue="test")
+assert msg.body == b"Received: Hello, RabbitMQ!"
+```
+
+The subscriber processes the request and sends back the response, which is received by the client.
+
+!!! tip
+    You can use the `no_reply=True` flag in the `#!python @broker.subscriber` decorator to suppress automatic RPC and `reply_to` responses.
+    This is useful when you want the subscriber to process the message without sending a response back to the client.
+
+## Using the Response class
+
+The `Response` class allows you to attach metadata, such as headers, to the response message.
+This is useful for adding context or tracking information to your responses.
+
+Below is an example of how to use the `Response` class in an RPC subscriber.
+
+```python linenums="1" hl_lines="1 8-12"
+from faststream import Response
+from faststream.rabbit import RabbitBroker
+
+broker = RabbitBroker()
+
+@broker.subscriber("test")
+async def handle(msg):
+    return Response(
+        body=f"Processed: {msg}",
+        headers={"x-token": "some-token"},
+        correlation_id="some-correlation-id",
+    )
+```
+
+When the client sends a request:
+
+```python linenums="1" hl_lines="4-6"
+from faststream.rabbit import RabbitMessage
+
+msg: RabbitMessage = await broker.request("Hello, RabbitMQ!", queue="test")
+assert msg.body == b"Processed: Hello, RabbitMQ!"
+assert msg.headers == {"x-token": "some-token"}
+assert msg.correlation_id == "some-correlation-id"
+```
+
+## Using the RabbitResponse class
+
+For RabbitMQ-specific use cases, you can use the `RabbitResponse` class instead of the generic `Response` class.
+
+The `RabbitResponse` class extends `Response` and adds support for RabbitMQ-specific message properties, such as `message_id`, `priority`, `expiration`, and more.
+
+This is particularly useful when you need fine-grained control over the message properties in a RabbitMQ context.
+
+Below is an example of how to use the `RabbitResponse` class in an RPC subscriber.
+
+```python linenums="1" hl_lines="1 7-14"
+from faststream.rabbit import RabbitBroker, RabbitResponse
+
+broker = RabbitBroker()
+
+@broker.subscriber("test")
+async def handle(msg):
+    return RabbitResponse(
+        body=f"Processed: {msg}",
+        headers={"x-token": "some-token"},
+        correlation_id="some-correlation-id",
+        message_id="unique-message-id",
+        priority=1,
+        mandatory=True,
+    )
+```

docs/docs/en/redis/rpc.md

@@ -56,3 +56,97 @@ Combining all the code snippets above, here is the complete example of how to se
 ```
 
 By embracing **Redis** RPC with **FastStream**, you can build sophisticated message-based architectures that require direct feedback from message processors. This feature is particularly suitable for cases where immediate processing is necessary or calling functions across different services is essential.
+
+## Creating an RPC subscriber
+
+To handle an RPC request, you need to create a subscriber that processes the incoming message and returns a response.
+The subscriber should be decorated with `#!python @broker.subscriber` and return either a raw value or a `Response` object.
+
+Below is an example of a simple RPC subscriber that processes a message and returns a response.
+
+```python linenums="1" hl_lines="7"
+from faststream.redis import RedisBroker
+
+broker = RedisBroker()
+
+@broker.subscriber(channel="test-channel")
+async def handle(msg):
+    return f"Received: {msg}"
+```
+
+When the client sends a request like this:
+
+```python  linenums="1" hl_lines="3"
+from faststream.redis import RedisMessage
+
+msg: RedisMessage = await broker.request(
+    "Hello, Redis!",
+    channel="test-channel",
+)
+assert await msg.decode() == "Received: Hello, Redis!"
+```
+
+The subscriber processes the request and sends back the response, which is received by the client.
+
+!!! tip
+    You can use the `no_reply=True` flag in the `#!python @broker.subscriber` decorator to suppress automatic RPC and `reply_to` responses.
+    This is useful when you want the subscriber to process the message without sending a response back to the client.
+
+## Using the Response class
+
+The `Response` class allows you to attach metadata, such as headers, to the response message.
+This is useful for adding context or tracking information to your responses.
+
+Below is an example of how to use the `Response` class in an RPC subscriber.
+
+```python linenums="1" hl_lines="1 8-12"
+from faststream import Response
+from faststream.redis import RedisBroker
+
+broker = RedisBroker()
+
+@broker.subscriber(channel="test-channel")
+async def handle(msg):
+    return Response(
+        body=f"Processed: {msg}",
+        headers={"x-token": "some-token"},
+        correlation_id="some-correlation-id",
+    )
+```
+
+When the client sends a request:
+
+```python linenums="1" hl_lines="7-9"
+from faststream.redis import RedisMessage
+
+msg: RedisMessage = await broker.request(
+    "Hello, Redis!",
+    channel="test-channel",
+)
+assert msg.body == b"Processed: Hello, Redis!"
+assert msg.headers == {"x-token": "some-token"}
+assert msg.correlation_id == "some-correlation-id"
+```
+
+## Using the RedisResponse class
+
+For Redis-specific use cases, you can use the `RedisResponse` class instead of the generic `Response` class.
+
+The `RedisResponse` class extends `Response` and adds support for specifying a `maxlen` parameter, which is useful when publishing responses to a Redis stream to limit the stream's length. This option could be helpful with Reply-To feature, when reply-to destination is a Redis stream.
+
+Below is an example of how to use the RedisResponse class in an RPC subscriber.
+
+```python linenums="1" hl_lines="1 7-12"
+from faststream.redis import RedisBroker, RedisResponse
+
+broker = RedisBroker()
+
+@broker.subscriber(stream="test-stream")
+async def handle(msg):
+    return RedisResponse(
+        body=f"Processed: {msg}",
+        headers={"x-token": "some-token"},
+        correlation_id="some-correlation-id",
+        maxlen=1000,
+    )
+```