Clarify OpenID base URL usage in Docker environments

docs/usage.rst

@@ -220,8 +220,9 @@ separate client is then configured using the :code:`swagger_client_id`  paramete
         add_swagger_auth=True
     )
 
-There are three more parameters that can be used to customize the Swagger UI integration:
+There are four more parameters that can be used to customize the Swagger UI integration:
 
+* :code:`swagger_openId_base_url` - The base URL for the OpenID Connect configuration that will be used by the Swagger UI. It is explained in this :issue:`65`. This parameter allows you to specify a different base URL than the one in keycloak_configuration.url. This is particularly useful in Docker container scenarios where the internal and external URLs differ. Defaults to using the keycloak_configuration.url.
 * :code:`swagger_auth_scopes` - The scopes that should be selected by default when hitting the Authorize button in Swagger UI. Defaults to :code:`['openid', 'profile']`
 * :code:`swagger_auth_pkce` - Whether to use PKCE for the Swagger UI client. Defaults to :code:`True`. It is recommended to use Authorization Code Flow with PKCE for public clients instead of implicit flow. In Keycloak, this flow is called "Standard flow"
 * :code:`swagger_scheme_name` - The name of the OpenAPI security scheme. Usually there is no need to change this.

fastapi_keycloak_middleware/setup.py

@@ -30,6 +30,7 @@ def setup_keycloak_middleware(  # pylint: disable=too-many-arguments
     | None = None,
     add_exception_response: bool = True,
     add_swagger_auth: bool = False,
+    swagger_openId_base_url: str | None = None,
     swagger_auth_scopes: typing.List[str] | None = None,
     swagger_auth_pkce: bool = True,
     swagger_scheme_name: str = "keycloak-openid",
@@ -66,6 +67,24 @@ def setup_keycloak_middleware(  # pylint: disable=too-many-arguments
     :param add_swagger_auth: Whether to add OpenID Connect authentication to the OpenAPI
         schema. Defaults to False.
     :type add_swagger_auth: bool, optional
+    :param swagger_openId_base_url: Base URL for the OpenID Connect configuration that will be used
+        by the Swagger UI. This parameter allows you to specify a different base URL than
+        the one in keycloak_configuration.url. This is particularly useful in Docker
+        container scenarios where the internal and external URLs differ.
+
+        For example, inside a Docker container network, Keycloak's OpenID configuration
+        endpoint might be available at:
+        http://host.docker.internal:8080/auth/realms/master/.well-known/openid-configuration
+
+        However, external clients like Swagger UI cannot resolve host.docker.internal.
+        In this case, you would set:
+        - keycloak_configuration.url:
+        -- "http://host.docker.internal:8080" (for internal communication)
+        - swagger_openId_base_url:
+        -- "http://localhost:8080" (for Swagger UI access)
+
+        If not specified, defaults to using keycloak_configuration.url.
+    :type swagger_openId_base_url: str, optional
     :param swagger_auth_scopes: Scopes to use for the Swagger UI authentication.
         Defaults to ['openid', 'profile'].
     :type swagger_auth_scopes: typing.List[str], optional
@@ -115,9 +134,10 @@ def setup_keycloak_middleware(  # pylint: disable=too-many-arguments
 
     # Add OpenAPI schema
     if add_swagger_auth:
-        suffix = "/.well-known/openid-configuration"
+        suffix = ".well-known/openid-configuration"
+        openId_base_url = swagger_openId_base_url or keycloak_configuration.url
         security_scheme = OpenIdConnect(
-            openIdConnectUrl=f"{keycloak_configuration.url}realms/{keycloak_configuration.realm}{suffix}",
+            openIdConnectUrl=f"{openId_base_url}/realms/{keycloak_configuration.realm}/{suffix}",
             scheme_name=swagger_scheme_name,
             auto_error=False,
         )