FastAPI

Installation

pip install scalar-fastapi

Usage

FastAPI makes it super easy to enable Scalar with their out of the box OpenAPI support.

Basic Usage

from fastapi import FastAPI
from scalar_fastapi import get_scalar_api_reference

app = FastAPI()

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

@app.get("/scalar", include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(
        # Your OpenAPI document
        openapi_url=app.openapi_url,
        # Avoid CORS issues (optional)
        scalar_proxy_url="https://proxy.scalar.com",
    )

Multiple OpenAPI Sources

You can now display multiple OpenAPI documents in a single Scalar instance:

from scalar_fastapi import get_scalar_api_reference, OpenAPISource

@app.get("/scalar", include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(
        sources=[
            OpenAPISource(
                title="User API",
                url="/openapi.json",
                default=True
            ),
            OpenAPISource(
                title="Admin API",
                url="/admin/openapi.json"
            ),
            OpenAPISource(
                title="External API",
                content='{"openapi": "3.0.0", ...}'
            )
        ],
        title="My API Documentation"
    )

Direct OpenAPI Content

You can pass OpenAPI content directly as a string or dictionary:

@app.get("/scalar", include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(
        content='{"openapi": "3.0.0", "info": {"title": "My API"}}',
        title="My API"
    )

Configuration

Currently available configuration options are listed below.

Core Configuration

• openapi_url (default None) - The OpenAPI URL that Scalar should load. If content or sources are provided, this parameter is ignored.
• content (default None) - Directly pass an OpenAPI/Swagger document as a string (JSON or YAML) or as a dictionary. If sources are provided, this parameter is ignored.
• sources (default None) - Add multiple OpenAPI documents to render all of them. Each source can have a title, slug, url, content, and default flag.
• title (default "Scalar") - The title of the API reference page

OpenAPISource Configuration

When using multiple sources, each OpenAPISource can be configured with:

• title (default None) - Display name for the API. If not provided, will fallback to 'API #1', 'API #2', etc.
• slug (default None) - URL identifier for the API. If not provided, will be auto-generated from the title or index.
• url (default None) - URL to the OpenAPI document (JSON or YAML). Mutually exclusive with content.
• content (default None) - Direct OpenAPI content as string (JSON/YAML) or dictionary. Mutually exclusive with url.
• default (default False) - Whether this source should be the default when multiple sources are provided.

Display Options

• layout (default Layout.MODERN)
• show_sidebar (default True)
• hide_models (default False)
• hide_search (default False) - Whether to show the sidebar search bar
• hide_test_request_button (default False) - Whether to show the "Test Request" button
• hide_download_button (default False) - Deprecated: Use document_download_type instead
• document_download_type (default DocumentDownloadType.BOTH) - Sets the file type of the document to download. Options: JSON, YAML, BOTH, NONE

DocumentDownloadType

from scalar_fastapi import DocumentDownloadType

# Available options:
DocumentDownloadType.JSON    # Download as JSON only
DocumentDownloadType.YAML    # Download as YAML only
DocumentDownloadType.BOTH    # Download as both JSON and YAML
DocumentDownloadType.NONE    # Hide download button

Theme and Appearance

• dark_mode (default True)
• force_dark_mode_state (default None) - Force dark mode state to always be this state. Can be 'dark' or 'light'
• hide_dark_mode_toggle (default False) - Whether to show the dark mode toggle
• with_default_fonts (default True) - Whether to use default fonts (Inter and JetBrains Mono)
• custom_css (default "") - Custom CSS string to apply to the API reference

Search and Navigation

• search_hot_key (default SearchHotKey.K)
• default_open_all_tags (default False)
• expand_all_model_sections (default False) - Whether to expand all model sections by default
• expand_all_responses (default False) - Whether to expand all response sections by default
• order_required_properties_first (default True) - Whether to order required properties first in schema objects

Server Configuration

• base_server_url (default "") - If you want to prefix all relative servers with a base URL
• servers (default [])
• hidden_clients (default [])

Authentication

• authentication (default {})
• hide_client_button (default False) - Whether to show the client button from the reference sidebar and modal
• persist_auth (default False) - Whether to persist authentication credentials in local storage

Advanced

• scalar_js_url (default "https://cdn.jsdelivr.net/npm/@scalar/api-reference")
• scalar_proxy_url (default None)
• integration (default None)
• theme (default Theme.DEFAULT)

Layout

from scalar_fastapi import Layout

# Available options:
Layout.MODERN    # Modern layout
Layout.CLASSIC   # Classic layout

SearchHotKey

from scalar_fastapi import SearchHotKey

# Available options:
SearchHotKey.K    # Use 'K' key
SearchHotKey.CMD_K # Use 'Cmd+K' (Mac) / 'Ctrl+K' (Windows/Linux)
SearchHotKey.NONE # Disable hotkey

Theme

from scalar_fastapi import Theme

# Available options:
Theme.DEFAULT # Default theme
Theme.NONE    # No theme