fix: added example for dynamic token auth

Author: aaltat

README.md

@@ -56,3 +56,54 @@ Wrapper
     Call And Validate    ${case}
 
 ```
+
+# Authentication
+
+## Dynamic token authentication
+Library currently supports Schemathesis
+[dynamic token](https://schemathesis.readthedocs.io/en/stable/guides/auth/#dynamic-token-authentication)
+authentication by the library import `auth` argument. The dynamic token generation
+class should follow the Schemathesis documentation. The only addition is the import.
+Importing the class must follow the Robot Framework library
+[import rules](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#specifying-library-to-import)
+, example if importing with filename, filename much match to the class name. Example
+if test case looks like:
+
+```robotframework
+*** Settings ***
+Library             SchemathesisLibrary    url=http://127.0.0.1/openapi.json    auth=${CURDIR}/AuthExtension.py
+Test Template       Wrapper
+
+*** Test Cases ***
+All Tests
+    Wrapper    test_case_1
+
+*** Keywords ***
+Wrapper
+    [Arguments]    ${case}
+    Call And Validate    ${case}
+```
+And `AuthExtension.py` looks like
+```python
+from base64 import b64encode
+
+import schemathesis
+from robot.api import logger
+
+
+@schemathesis.auth()
+class AuthExtension:
+    def get(self, case, ctx):
+        # Instead of hard coding secrets to class, it is better to get them dynamically.
+        # Jenkins or GitHub secrets, Azure keyvault, or from somewhere which is appropriate
+        # for your needs.
+        return b64encode("joulu:pukki".encode("utf-8")).decode("ascii")
+
+    def set(self, case, data, ctx):
+        case.headers = case.headers or {}
+        case.headers["Authorization"] = f"Basic {data}"
+        logger.debug(f"Updated headers for case: {case.operation.method} {case.operation.path}")
+```
+Then with all API calls, will have
+[basic auth](https://en.wikipedia.org/wiki/Basic_access_authentication) set in the
+headers for all calls made to your API endpoint.

src/SchemathesisLibrary/__init__.py

@@ -88,6 +88,22 @@ def __init__(
         | `path`                            | Path to the OpenAPI schema file. Using either `path` or `url` is mandatory. |
         | `url`                             | URL where the OpenAPI schema can be downloaded. |
         | `auth`                            | Optional authentication class to be used passed for Schemathesis authentication when test cases are executed. |
+
+        The `headers` argument is only needed when the schema is downloaded from a URL and there is need to pass example
+        authentication headers to the endpoint. `headers` is not used the API calls are made during test execution.
+
+        `path` and `url` are mutually exclusive, only one of them should be used to specify the OpenAPI schema location.
+
+        `auth` can be used create Schemathesis
+        [https://schemathesis.readthedocs.io/en/stable/guides/auth/#dynamic-token-authentication|dynamic token]
+        authentication for the test cases. The dynamic token generation class should
+        follow the Schemathesis documentation. The only addition is the import. Importing
+        the class must follow the Robot Framework library
+        [https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#specifying-library-to-import|import rules]
+        , example if importing with filename, filename much match to the class name.
+        See example from
+        [https://github.com/aaltat/robotframework-schemathesis?tab=readme-ov-file##dynamic-token-authentication|README.md]
+        file
         """
         self.ROBOT_LIBRARY_LISTENER = self
         SchemathesisReader.options = Options(