Scalar FastAPI

1.8.2 · active · verified Sat Apr 11

Scalar FastAPI is a Python plugin that enhances the default FastAPI documentation experience by rendering a beautiful, interactive API reference based on the OpenAPI/Swagger specification. It provides a modern, responsive UI and a developer-first experience, offering extensive customization options for branding and layout. The library is actively maintained, with frequent updates to its underlying JavaScript components reflected in new Python wrapper releases.

Warnings

gotcha Telemetry is enabled by default. To disable usage telemetry for privacy or compliance, explicitly set `telemetry=False` in the `get_scalar_api_reference` call.
Fix: Pass `telemetry=False` to `get_scalar_api_reference()`.
gotcha The AI Chat 'Agent' feature is enabled by default on localhost with limited free messages. For production environments, an Agent key is required for full functionality. Failing to provide a key will limit or disable the AI features.
Fix: For production, configure `agent=AgentScalarConfig(key="your-agent-scalar-key")` in `get_scalar_api_reference` or per `OpenAPISource`.
deprecated The `hide_download_button` parameter in `get_scalar_api_reference` is deprecated. Use `document_download_type` instead to control the visibility and type of the OpenAPI document download button.
Fix: Replace `hide_download_button=True` with `document_download_type=DocumentDownloadType.NONE` (or `JSON`, `YAML`, `BOTH` as needed).
gotcha When serving the OpenAPI document from a different origin than Scalar (e.g., local development vs. hosted Scalar), CORS issues might occur. The documentation recommends using `scalar_proxy_url` to mitigate these problems.
Fix: Pass `scalar_proxy_url="https://proxy.scalar.com"` (or your own proxy URL) to `get_scalar_api_reference()`.
gotcha The `scalar-fastapi` Python package wraps a core JavaScript frontend library. While the underlying JS components (e.g., `@scalar/api-client`, `@scalar/api-reference`) receive very frequent updates and potentially major changes, the Python wrapper's release cycle is less frequent. Python users might experience a slight delay in new frontend features or minor breaking changes being reflected in the `scalar-fastapi` version.
Fix: Check the `scalar-fastapi` changelog (`integrations/fastapi/CHANGELOG.md` in the main Scalar GitHub repo) for Python-specific updates and breaking changes rather than solely relying on the overall Scalar project's release notes.

Install

pip install scalar-fastapi uvicorn Install library and Uvicorn

Imports

get_scalar_api_reference

from scalar_fastapi import get_scalar_api_reference

OpenAPISource
```
from scalar_fastapi import get_scalar_api_reference, OpenAPISource
```
Used for providing multiple OpenAPI sources to the documentation.
Layout
```
from scalar_fastapi import Layout
```
Provides options for customizing the documentation layout.
Theme
```
from scalar_fastapi import Theme
```
Provides options for customizing the documentation theme.

Quickstart

This example sets up a basic FastAPI application and integrates Scalar documentation at the `/scalar` endpoint. It uses `app.openapi_url` to automatically load the API's schema. Run with `uvicorn main:app --reload` and navigate to `/scalar`.

from fastapi import FastAPI
from scalar_fastapi import get_scalar_api_reference
import uvicorn

app = FastAPI(
    title="My Awesome API",
    description="A simple FastAPI application to demonstrate Scalar docs.",
    version="1.0.0",
)

@app.get("/")
async def read_root():
    return {"message": "Hello, World!"}

@app.get("/scalar", include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(
        openapi_url=app.openapi_url,
        title=app.title,
        # Optional: Avoid CORS issues with a proxy
        # scalar_proxy_url="https://proxy.scalar.com",
        # Optional: Disable telemetry
        # telemetry=False
    )

# To run: uvicorn main:app --reload
# Then open http://127.0.0.1:8000/scalar in your browser

view raw JSON →