improve documentation

Author: alukach

docs/user-guide/tips.md

@@ -2,12 +2,12 @@
 
 ## CORS
 
-The STAC Auth Proxy does not modify the [CORS response headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS#the_http_response_headers) from the upstream STAC API. All CORS configuration must be handled by the upstream API.  
+The STAC Auth Proxy does not modify the [CORS response headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS#the_http_response_headers) from the upstream STAC API. All CORS configuration must be handled by the upstream API.
 
 Because the STAC Auth Proxy introduces authentication, the upstream API’s CORS settings may need adjustment to support credentials. In most cases, this means:
 
-* [`Access-Control-Allow-Credentials`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Credentials) must be `true`  
-* [`Access-Control-Allow-Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Origin) must _not_ be `*`[^CORSNotSupportingCredentials]  
+- [`Access-Control-Allow-Credentials`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Credentials) must be `true`
+- [`Access-Control-Allow-Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Origin) must _not_ be `*`[^CORSNotSupportingCredentials]
 
 [^CORSNotSupportingCredentials]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSNotSupportingCredentials
 
@@ -32,13 +32,40 @@ Rather than performing the login flow, the Swagger UI can be configured to accep
 ```sh
 OPENAPI_AUTH_SCHEME_NAME=jwtAuth
 OPENAPI_AUTH_SCHEME_OVERRIDE='{
-  "type": "http", 
-  "scheme": "bearer", 
-  "bearerFormat": "JWT", 
+  "type": "http",
+  "scheme": "bearer",
+  "bearerFormat": "JWT",
   "description": "Paste your raw JWT here. This API uses Bearer token authorization."
 }'
 ```
 
-## Runtime Customization
+## Non-proxy Configuration
 
-While the project is designed to work out-of-the-box as an application, it might not address every projects needs. When the need for customization arises, the codebase can instead be treated as a library of components that can be used to augment any [ASGI](https://asgi.readthedocs.io/en/latest/)-compliant webserver (e.g. [Django](https://docs.djangoproject.com/en/3.0/topics/async/), [Falcon](https://falconframework.org/), [FastAPI](https://github.com/tiangolo/fastapi), [Litestar](https://litestar.dev/), [Responder](https://responder.readthedocs.io/en/latest/), [Sanic](https://sanic.dev/), [Starlette](https://www.starlette.io/)). Review [`app.py`](https://github.com/developmentseed/stac-auth-proxy/blob/main/src/stac_auth_proxy/app.py) to get a sense of how we make use of the various components to construct a FastAPI application.
+While the project is designed to work out-of-the-box as an application, it might not address every projects needs. When the need for customization arises, the codebase can instead be treated as a library of components that can be used to augment a FastAPI server. This may look something like the following:
+
+```py
+from fastapi import FastAPI
+from stac_fastapi.api.app import StacApi
+from stac_auth_proxy import build_lifespan, configure_app, Settings as StacAuthSettings
+
+# Create Auth Settings
+auth_settings = StacAuthSettings(
+  upstream_url='https://stac-server',
+  oidc_discovery_url='https://auth-server/.well-known/openid-configuration',
+)
+
+# Setup App
+app = FastAPI(
+  ...
+  lifespan=build_lifespan(auth_settings),
+)
+
+# Apply STAC Auth Proxy middleware
+configure_app(app, auth_settings)
+
+# Setup STAC API
+api = StacApi(
+  app,
+  ...
+)
+```

src/stac_auth_proxy/__init__.py

@@ -8,8 +8,10 @@
 
 from .app import configure_app, create_app
 from .config import Settings
+from .lifespan import build_lifespan
 
 __all__ = [
+    "build_lifespan",
     "create_app",
     "configure_app",
     "Settings",

src/stac_auth_proxy/app.py

@@ -6,7 +6,7 @@
 """
 
 import logging
-from typing import Optional
+from typing import Any, Optional
 
 from fastapi import FastAPI
 from starlette_cramjam.middleware import CompressionMiddleware
@@ -30,9 +30,26 @@
 logger = logging.getLogger(__name__)
 
 
-def configure_app(app: FastAPI, settings: Optional[Settings] = None) -> FastAPI:
-    """Apply routes and middleware to a FastAPI app."""
-    settings = settings or Settings()
+def configure_app(
+    app: FastAPI,
+    settings: Optional[Settings] = None,
+    **settings_kwargs: Any,
+) -> FastAPI:
+    """
+    Apply routes and middleware to a FastAPI app.
+
+    Parameters
+    ----------
+    app : FastAPI
+        The FastAPI app to configure.
+    settings : Settings | None, optional
+        Pre-built settings instance. If omitted, a new one is constructed from
+        ``settings_kwargs``.
+    **settings_kwargs : Any
+        Keyword arguments used to configure the health and conformance checks if
+        ``settings`` is not provided.
+    """
+    settings = settings or Settings(**settings_kwargs)
 
     #
     # Route Handlers