{"id":3983,"library":"drf-spectacular-sidecar","title":"DRF Spectacular Sidecar","description":"drf-spectacular-sidecar is a Django application that serves self-contained distribution builds of Swagger UI and Redoc. It acts as an optional addition to `drf-spectacular` for environments without CDN access, but can also be used independently. The project is actively maintained, with versions updated monthly (around the 1st) by sourcing distribution files from npm via jsdelivr. The current version is 2026.4.1.","status":"active","version":"2026.4.1","language":"en","source_language":"en","source_url":"https://github.com/tfranzel/drf-spectacular-sidecar","tags":["django","drf","rest-framework","openapi","swagger","redoc","documentation","static-files"],"install":[{"cmd":"pip install drf-spectacular-sidecar","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for integration as a Django application.","package":"Django","optional":false},{"reason":"Typically used in conjunction with drf-spectacular to provide local Swagger UI/Redoc assets.","package":"drf-spectacular","optional":true}],"imports":[{"note":"The library itself is a Django app that provides static files; it's activated by adding it to INSTALLED_APPS, not by direct Python imports for typical usage.","symbol":"drf_spectacular_sidecar","correct":"INSTALLED_APPS = [\n    # ...\n    'drf_spectacular_sidecar',\n    # ...\n]"}],"quickstart":{"code":"# settings.py\nINSTALLED_APPS = [\n    # ... your other apps\n    'drf_spectacular_sidecar',\n    'drf_spectacular', # Only if you are using drf-spectacular\n    # ...\n]\n\n# Only if you are using drf-spectacular and want to use the sidecar for UI assets\nSPECTACULAR_SETTINGS = {\n    'SWAGGER_UI_DIST': 'SIDECAR',\n    'SWAGGER_UI_FAVICON_HREF': 'SIDECAR',\n    'REDOC_DIST': 'SIDECAR',\n    # ... other drf-spectacular settings\n}","lang":"python","description":"After installation, add `drf_spectacular_sidecar` to your Django project's `INSTALLED_APPS`. If you are using `drf-spectacular`, configure `SPECTACULAR_SETTINGS` to point `SWAGGER_UI_DIST`, `SWAGGER_UI_FAVICON_HREF`, and `REDOC_DIST` to `'SIDECAR'` to utilize the locally served assets."},"warnings":[{"fix":"Consult the `drf-spectacular` FAQ on CSP issues for specific `SPECTACULAR_SETTINGS` and `CSP_DEFAULT_SRC` adjustments.","message":"Content Security Policy (CSP) errors, especially with libraries like `django-csp`, can prevent Swagger UI or Redoc from displaying correctly. The sidecar mitigates issues with external asset loading, but you might still need to adjust `CSP_DEFAULT_SRC` for `unsafe-inline` scripts or consider `SpectacularSwaggerSplitView` as an alternative.","severity":"gotcha","affected_versions":"All versions"},{"fix":"This is a complex issue; refer to `drf-spectacular` GitHub issues #718 and #847 for potential workarounds or updates. A common fix involves ensuring proper usage of Django's staticfiles storage mechanisms or overriding URL resolution.","message":"When using custom static file storage backends (e.g., `ManifestStaticFilesStorage`, Amazon S3 via `django-storages`), the sidecar may fail to correctly resolve static file paths, leading to broken UI or `collectstatic` errors. This often manifests as attempts to load from `/static/` instead of the configured storage.","severity":"breaking","affected_versions":"Versions affected by drf-spectacular issues #718 and #847 (specifically from 2022.4.x onwards that incorporated changes related to #718)."},{"fix":"Ensure `drf_spectacular_sidecar` is explicitly listed in `INSTALLED_APPS`.","message":"It is crucial to add `'drf_spectacular_sidecar'` to your `INSTALLED_APPS` in `settings.py`. Failing to do so will prevent Django from discovering and serving the necessary static files for Swagger UI and Redoc, resulting in blank or non-functional documentation pages.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Understand that the sidecar provides the raw static assets for the UI, which `drf-spectacular` then uses to render the documentation pages at specified URLs (e.g., `/api/schema/swagger-ui/`).","message":"The `drf-spectacular-sidecar` package is intended to serve static UI files locally, not to integrate a documentation interface directly into the Django Admin. Misunderstanding this purpose can lead to incorrect expectations about its functionality.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}