doc - improve RequestBase

aiopenapi3/request.py

@@ -35,6 +35,7 @@ async def aclosing(thing):
         RequestData,
         RequestFiles,
         RequestContent,
+        RequestType,
         AuthTypes,
         SchemaType,
         ParameterType,
@@ -96,12 +97,39 @@ def __init__(
         servers: Optional[List["ServerType"]],
     ):
         self.api: "OpenAPI" = api
+        """
+        OpenAPI object
+        """
+
         self.root = api._root  # pylint: disable=W0212
+        """
+        API document root
+        """
+
         self.method: "HTTPMethodType" = method
+        """
+        HTTP method
+        """
+
         self.path: str = path
+        """
+        HTTP path
+        """
+
         self.operation: "OperationType" = operation
+        """
+        associated OpenAPI Operation
+        """
+
         self.req: RequestParameter = RequestParameter(self.path)
+        """
+        RequestParameter
+        """
+
         self.servers: Optional[List["ServerType"]] = servers
+        """
+        Servers to use for this request
+        """
 
     def __call__(self, *args, return_headers: bool = False, **kwargs) -> Union["JSON", Tuple[Dict[str, str], "JSON"]]:
         """
@@ -378,7 +406,13 @@ def __init__(self, api: "OpenAPI", use_operation_tags: bool):
         self._tags = dict(self._tags)
         self._use_operation_tags = use_operation_tags
 
-    def __getattr__(self, item):
+    def __getattr__(self, item: str) -> "RequestType":
+        """
+        the sad smiley interface
+
+        :param item: the operationId
+        :return:
+        """
         if self._use_operation_tags and item in self._tags:
             return self._tags[item]
         elif item in self._operations:
@@ -387,14 +421,17 @@ def __getattr__(self, item):
         else:
             raise KeyError(f"operationId {item} not found in tags or operations")
 
-    def __getitem__(self, item: Union[str, Tuple[str, "HTTPMethodType"]]):
+    def __getitem__(self, item: Union[str, Tuple[str, "HTTPMethodType"]]) -> "RequestType":
         """
         index operator interface
         access operations by operationId or (path, method)
+
+        :param item: operationId or tuple of path & method
+        :return:
         """
         return getattr(self, item) if isinstance(item, str) else self._api.createRequest(item)
 
-    def __iter__(self):
+    def __iter__(self) -> "OpenationIndex.Iter":
         return self.Iter(self._root, self._use_operation_tags)
 
     def __getstate__(self):

docs/source/api.rst

@@ -20,19 +20,19 @@ Requests
 Requests encapsulate the required information to call an operation.
 They
 
-    - compile the actual HTTP request sent, including authentication information, headers, parameters and the body.
+    - compile the actual HTTP request to be sent, including authentication information, path, headers, parameters and the body.
     - send it
     - receive the result
     - process it
     - and return the model of the data
 
 .. currentmodule:: aiopenapi3.request
 .. autoclass:: RequestBase
-    :members: data, parameters, request, stream, __call__
+    :members: data, parameters, request, stream, __call__, operation, root
 
 .. currentmodule:: aiopenapi3.request
 .. autoclass:: AsyncRequestBase
-    :members: data, parameters, request, stream, __call__
+    :members: data, parameters, request, stream, __call__, operation, root
 
 
 The different major versions of the OpenAPI protocol require their own Request/AsyncRequest.
@@ -46,6 +46,13 @@ The different major versions of the OpenAPI protocol require their own Request/A
 .. autoclass:: aiopenapi3.v30.glue.AsyncRequest
 
 
+OperationIndex
+==============
+.. currentmodule:: aiopenapi3.request
+.. autoclass:: OperationIndex
+    :members: __getattr__, __getitem__
+
+
 Parameters
 ==========
 

docs/source/use.rst

@@ -64,7 +64,36 @@ refer to :ref:`advanced:Authentication` for details.
 
 Creating a request
 ------------------
-The service `operations <https://try.gitea.io/api/swagger>`_ can be accessed via the sad smiley interface.
+While there is multiple ways to access a service `operations <https://try.gitea.io/api/swagger>`_, all return a Request which can be called.
+
+The sad smiley interface :meth:`aiopenapi3.request.OperationIndex.__getattr__`.
+
+.. code:: python
+
+    req = api._.getUser
+    m = req()
+    m.id == user.id
+    # True
+
+
+or, in case the PathItem does not have an operationId, it is possible to create a request via :meth:`aiopenapi3.request.OperationIndex.__getitem__`
+
+.. code:: python
+
+    req = api._[("/user", "get")]
+    m = req()
+    m.id == user.id
+    # True
+
+or :meth:`aiopenapi3.OpenAPI.createRequest`.
+
+.. code:: python
+
+    req = api.createRequest(("/user", "get"))
+    m = req()
+    m.id == user.id
+    # True
+
 
 A list of all operations with operationIds exported by the service is available via the Iter.
 
@@ -85,15 +114,9 @@ Creating a request to the service and inspecting the result:
     # "2022-12-07 16:50:07+00:00"
     type(user.created)
 
-In case the PathItem does not have an operationId, it is possible to create a request via
-:meth:`aiopenapi3.OpenAPI.createRequest`.
 
-.. code:: python
 
-    req = api.createRequest(("/user", "get"))
-    m = req()
-    m.id == user.id
-    # True
+For more information of mentioned return valuew of type :meth:`aiopenapi3.request.RequestBase` refer to :ref:`api:Requests`.
 
 Using Operation Tags
 --------------------