docs: Update docstrings for haystack.components.connectors (#7267)

* OpenAPIServiceConnector review and normalize docstrings

* PR feedback Stefano

haystack/components/connectors/openapi_service.py

@@ -16,15 +16,51 @@ with LazyImport("Run 'pip install openapi3'") as openapi_imports:
 @component
 class OpenAPIServiceConnector:
     """
-    OpenAPIServiceConnector connects to OpenAPI services, allowing for the invocation of methods specified in
-    an OpenAPI specification of that service. It integrates with ChatMessage interface, where messages are used to
-    determine the method to be called and the parameters to be passed. The message payload should be a JSON formatted
+    The `OpenAPIServiceConnector` component connects the Haystack framework to OpenAPI services, enabling it to call
+    operations as defined in the OpenAPI specification of the service.
+
+    It integrates with `ChatMessage` dataclass, where the payload in messages is used to determine the method to be
+    called and the parameters to be passed. The message payload should be an OpenAI JSON formatted function calling
     string consisting of the method name and the parameters to be passed to the method. The method name and parameters
     are then used to invoke the method on the OpenAPI service. The response from the service is returned as a
-    ChatMessage.
+    `ChatMessage`.
+
+    Before using this component, users usually resolve service endpoint parameters with a help of
+    `OpenAPIServiceToFunctions` component.
+
+    The example below demonstrates how to use the `OpenAPIServiceConnector` to invoke a method on a https://serper.dev/
+    service specified via OpenAPI specification.
+
+    Note, however, that `OpenAPIServiceConnector` is usually not meant to be used directly, but rather as part of a
+    pipeline that includes the `OpenAPIServiceToFunctions` component and an `OpenAIChatGenerator` component using LLM
+    with the function calling capabilities. In the example below we use the function calling payload directly, but in a
+    real-world scenario, the function calling payload would usually be generated by the `OpenAIChatGenerator` component.
+
+    Usage example:
+
+    ```python
+    import json
+    import requests
+
+    from haystack.components.connectors import OpenAPIServiceConnector
+    from haystack.dataclasses import ChatMessage
+
+
+    fc_payload = [{'function': {'arguments': '{"q": "Why was Sam Altman ousted from OpenAI?"}', 'name': 'search'},
+                   'id': 'call_PmEBYvZ7mGrQP5PUASA5m9wO', 'type': 'function'}]
+
+    serper_token = <your_serper_dev_token>
+    serperdev_openapi_spec = json.loads(requests.get("https://bit.ly/serper_dev_spec").text)
+    service_connector = OpenAPIServiceConnector()
+    result = service_connector.run(messages=[ChatMessage.from_assistant(json.dumps(fc_payload))],
+                                   service_openapi_spec=serperdev_openapi_spec, service_credentials=serper_token)
+    print(result)
+
+    >> {'service_response': [ChatMessage(content='{"searchParameters": {"q": "Why was Sam Altman ousted from OpenAI?",
+    >> "type": "search", "engine": "google"}, "answerBox": {"snippet": "Concerns over AI safety and OpenAI\'s role
+    >> in protecting were at the center of Altman\'s brief ouster from the company."...
+    ```
 
-    Before using this component, one needs to register functions from the OpenAPI specification with LLM.
-    This can be done using the OpenAPIServiceToFunctions component.
     """
 
     def __init__(self):
@@ -44,15 +80,19 @@ class OpenAPIServiceConnector:
         Processes a list of chat messages to invoke a method on an OpenAPI service. It parses the last message in the
         list, expecting it to contain an OpenAI function calling descriptor (name & parameters) in JSON format.
 
-        :param messages: A list of `ChatMessage` objects representing the chat history.
-        :type messages: List[ChatMessage]
-        :param service_openapi_spec: The OpenAPI JSON specification object of the service.
-        :type service_openapi_spec: JSON object
-        :return: A dictionary with a key `"service_response"`, containing the response from the OpenAPI service.
-        :rtype: Dict[str, List[ChatMessage]]
+        :param messages: A list of `ChatMessage` objects containing the messages to be processed. The last message
+        should contain the function invocation payload in OpenAI function calling format. See the example in the class
+        docstring for the expected format.
+        :param service_openapi_spec: The OpenAPI JSON specification object of the service to be invoked. All the refs
+        should already be resolved.
         :param service_credentials: The credentials to be used for authentication with the service.
-        Currently, only the http and apiKey schemes are supported. See _authenticate_service method for more details.
-        :type service_credentials: Optional[Union[dict, str]]
+        Currently, only the http and apiKey OpenAPI security schemes are supported.
+
+        :return: A dictionary with the following keys:
+            - `service_response`:  a list of `ChatMessage` objects, each containing the response from the service. The
+                                   response is in JSON format, and the `content` attribute of the `ChatMessage` contains
+                                   the JSON string.
+
         :raises ValueError: If the last message is not from the assistant or if it does not contain the correct payload
         to invoke a method on the service.
         """
@@ -84,9 +124,7 @@ class OpenAPIServiceConnector:
         Parses the message to extract the method invocation descriptor.
 
         :param message: ChatMessage containing the tools calls
-        :type message: ChatMessage
         :return: A list of function invocation payloads
-        :rtype: List[Dict[str, Any]]
         :raises ValueError: If the content is not valid JSON or lacks required fields.
         """
         function_payloads = []
@@ -124,10 +162,8 @@ class OpenAPIServiceConnector:
         names. If only one security scheme is defined, the credentials can be provided as a simple string.
 
         :param openapi_service: The OpenAPI service instance.
-        :type openapi_service: OpenAPI
         :param credentials: Credentials for authentication, which can be either a string (e.g. token) or a dictionary
         with keys matching the authentication method names.
-        :type credentials: dict | str, optional
         :raises ValueError: If authentication fails, is not found, or if appropriate credentials are missing.
         """
         if openapi_service.raw_element.get("components", {}).get("securitySchemes"):
@@ -169,13 +205,10 @@ class OpenAPIServiceConnector:
         method_invocation_descriptor.
 
         :param openapi_service: The OpenAPI service instance.
-        :type openapi_service: OpenAPI
         :param method_invocation_descriptor: The method name and arguments to be passed to the method. The payload
         should contain the method name (key: "name") and the arguments (key: "arguments"). The name is a string, and
         the arguments are a dictionary of key-value pairs.
-        :type method_invocation_descriptor: Dict[str, Any]
         :return: A service JSON response.
-        :rtype: Any
         :raises RuntimeError: If the method is not found or invocation fails.
         """
         name = method_invocation_descriptor.get("name")