docs: Fix chatclient.adoc responseEntity() documentation (spring-projects#4386)

- Correct inaccurate description of responseEntity() returning HTTP response details
- Add complete documentation for all three responseEntity() method overloads
- Reorder entity() and responseEntity() methods for logical flow
- Ensure consistency with entity() method documentation format

Auto-cherry-pick to 1.0.x
Fixes spring-projects#4386

Signed-off-by: YunKui Lu <[email protected]>
Signed-off-by: 家娃 <[email protected]>

Author: YunKuiLu

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc

@@ -365,12 +365,14 @@ After specifying the `call()` method on `ChatClient`, there are a few different
 * `String content()`: returns the String content of the response
 * `ChatResponse chatResponse()`: returns the `ChatResponse` object that contains multiple generations and also metadata about the response, for example how many token were used to create the response.
 * `ChatClientResponse chatClientResponse()`: returns a `ChatClientResponse` object that contains the `ChatResponse` object and the ChatClient execution context, giving you access to additional data used during the execution of advisors (e.g. the relevant documents retrieved in a RAG flow).
-* `ResponseEntity<?> responseEntity()`: returns a `ResponseEntity` containing the full HTTP response, including status code, headers, and body.
-This is useful when you need access to low-level HTTP details of the response.
 * `entity()` to return a Java type
 ** `entity(ParameterizedTypeReference<T> type)`: used to return a `Collection` of entity types.
 ** `entity(Class<T> type)`:  used to return a specific entity type.
 ** `entity(StructuredOutputConverter<T> structuredOutputConverter)`: used to specify an instance of a `StructuredOutputConverter` to convert a `String` to an entity type.
+* `responseEntity()` to return both the `ChatResponse` and a Java type. This is useful when you need access to both the complete AI model response (with metadata and generations) and the structured output entity in a single call.
+** `responseEntity(Class<T> type)`: used to return a `ResponseEntity` containing both the complete `ChatResponse` object and a specific entity type.
+** `responseEntity(ParameterizedTypeReference<T> type)`: used to return a `ResponseEntity` containing both the complete `ChatResponse` object and a `Collection` of entity types.
+** `responseEntity(StructuredOutputConverter<T> structuredOutputConverter)`: used to return a `ResponseEntity` containing both the complete `ChatResponse` object and an entity converted using a specified `StructuredOutputConverter`.
 
 You can also invoke the `stream()` method instead of `call()`.