feat: add Swagger UI support

- Introduced a new SwaggerUI handler to serve the Swagger UI interface.
- Updated app configuration to include Swagger UI parameters and routes.
- Enhanced Settings class with new fields for Swagger UI configuration.
- Ensured compatibility with OpenAPI spec endpoint when using Swagger UI.

Author: alukach

src/stac_auth_proxy/app.py

@@ -13,7 +13,7 @@
 from starlette_cramjam.middleware import CompressionMiddleware
 
 from .config import Settings
-from .handlers import HealthzHandler, ReverseProxyHandler
+from .handlers import HealthzHandler, ReverseProxyHandler, SwaggerUI
 from .middleware import (
     AddProcessTimeHeaderMiddleware,
     ApplyCql2FilterMiddleware,
@@ -68,6 +68,10 @@ async def lifespan(app: FastAPI):
 
     app = FastAPI(
         openapi_url=None,  # Disable OpenAPI schema endpoint, we want to serve upstream's schema
+        swagger_ui_parameters={
+            "usePkceWithAuthorizationCodeGrant": True,
+            "clientId": "stac-auth-proxy",
+        },
         lifespan=lifespan,
         root_path=settings.root_path,
     )
@@ -78,6 +82,20 @@ async def lifespan(app: FastAPI):
     # Handlers (place catch-all proxy handler last)
     #
 
+    if settings.swagger_ui_url:
+        assert (
+            settings.openapi_spec_endpoint
+        ), "openapi_spec_endpoint must be set when using swagger_ui_url"
+        app.add_route(
+            settings.swagger_ui_url,
+            SwaggerUI(
+                openapi_url=settings.openapi_spec_endpoint,
+                title=settings.swagger_ui_title,
+                init_oauth=settings.swagger_ui_init_oauth,
+                parameters=settings.swagger_ui_parameters,
+            ).route,
+            include_in_schema=False,
+        )
     if settings.healthz_prefix:
         app.include_router(
             HealthzHandler(upstream_url=str(settings.upstream_url)).router,

src/stac_auth_proxy/config.py

@@ -45,9 +45,16 @@ class Settings(BaseSettings):
     check_conformance: bool = True
     enable_compression: bool = True
 
-    openapi_spec_endpoint: Optional[str] = Field(pattern=_PREFIX_PATTERN, default=None)
+    # OpenAPI / Swagger UI
+    openapi_spec_endpoint: Optional[str] = Field(
+        pattern=_PREFIX_PATTERN, default="/api"
+    )
     openapi_auth_scheme_name: str = "oidcAuth"
     openapi_auth_scheme_override: Optional[dict] = None
+    swagger_ui_url: str = "/api.html"
+    swagger_ui_title: str = "STAC API"
+    swagger_ui_init_oauth: dict = Field(default_factory=dict)
+    swagger_ui_parameters: dict = Field(default_factory=dict)
 
     # Auth
     enable_authentication_extension: bool = True

src/stac_auth_proxy/handlers/__init__.py

@@ -2,5 +2,6 @@
 
 from .healthz import HealthzHandler
 from .reverse_proxy import ReverseProxyHandler
+from .swagger_ui import SwaggerUI
 
-__all__ = ["ReverseProxyHandler", "HealthzHandler"]
+__all__ = ["ReverseProxyHandler", "HealthzHandler", "SwaggerUI"]

src/stac_auth_proxy/handlers/swagger_ui.py

@@ -0,0 +1,35 @@
+"""Swagger UI handler."""
+
+from dataclasses import dataclass, field
+
+from fastapi.openapi.docs import get_swagger_ui_html
+from starlette.requests import Request
+from starlette.responses import HTMLResponse
+
+
+@dataclass
+class SwaggerUI:
+    """Swagger UI handler."""
+
+    openapi_url: str
+    title: str = "STAC API"
+    # https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/
+    init_oauth: dict = field(default_factory=dict)
+    # https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
+    parameters: dict = field(default_factory=dict)
+    oauth2_redirect_url: str = "/docs/oauth2-redirect"
+
+    async def route(self, req: Request) -> HTMLResponse:
+        """Route handler."""
+        root_path = req.scope.get("root_path", "").rstrip("/")
+        openapi_url = root_path + self.openapi_url
+        oauth2_redirect_url = self.oauth2_redirect_url
+        if oauth2_redirect_url:
+            oauth2_redirect_url = root_path + oauth2_redirect_url
+        return get_swagger_ui_html(
+            openapi_url=openapi_url,
+            title=f"{self.title} - Swagger UI",
+            oauth2_redirect_url=oauth2_redirect_url,
+            init_oauth=self.init_oauth,
+            swagger_ui_parameters=self.parameters,
+        )