csrd-versioning 0.5.0

API versioning, dispatch, docs, and actuator for FastAPI

csrd-versioning

API versioning, dispatch, docs, and actuator for FastAPI.

Package: csrd.versioning · Import: from csrd.versioning import compose_versioned_apps, configure_versioned_api

What's included

• Version dispatch — raw ASGI middleware for version-aware routing (streaming/SSE safe)
• Swagger UI — custom docs with version picker, dark mode, SRI hashes, plugin system
• Actuator — Spring Boot-style management endpoints (health, info, env)
• Exception handlers — structured APIErrorResponse JSON for HTTP and validation errors
• Dependency wiring — auto path-param injection, bearer guard opt-out

Installation

uv pip install "csrd-versioning @ git+ssh://[e-mail]/csrd-api/fastapi-common.git#subdirectory=packages/versioning"

Quick start

from enum import Enum
from fastapi import FastAPI
from csrd.versioning import compose_versioned_apps, VersionedApiConfig, VersionedAppComposeConfig

class Versions(Enum):
    Unversioned = "Unversioned"
    V1 = "2025-06-20"

unv = FastAPI()
v1 = FastAPI()

app = compose_versioned_apps(
    {Versions.Unversioned: unv, Versions.V1: v1},
    config=VersionedAppComposeConfig(
        api=VersionedApiConfig(prefix="api"),
    ),
)

Security notes

• /actuator/env: The ShowValues.ALWAYS setting exposes environment variable values. Use ShowValues.NEVER (default) in production to redact sensitive data.
• CORS: Add CORSMiddleware before calling configure_versioned_api. The version dispatch middleware must be the outermost middleware. Example:

app = FastAPI()
app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"], ...)
configure_versioned_api(app, version_mapping, ...)

Dependencies

• csrd-models, csrd-context (Tier 1 packages — csrd-versioning is Tier 3)
• For JWT auth, use csrd-auth alongside this package