API Reference for Django Ninja

Installation#

pip install scalar-ninja

Usage#

Integrating Scalar with Django Ninja is simple.

Basic Usage#

Just pass the ScalarViewer instance to the docs parameter of the NinjaAPI instance.

from ninja import NinjaAPI
from scalar_ninja import ScalarViewer
 
api = NinjaAPI(
    version="1.0.0",
    title="API Reference",
    description="API Reference for the Scalar Django Ninja Plugin",
    docs=ScalarViewer(),
)
 
@api.get("/add")
def add(request, a: int, b: int):
    return {"result": a + b}
 
 
urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/", api.urls),
]

This renders a beautiful API reference at /api/docs based on your API.

Advanced Usage#

You can configure ScalarViewer by passing ScalarConfig to the method. Detailed configuration options are listed here.

from ninja import NinjaAPI
from scalar_ninja import ScalarConfig, ScalarViewer
 
scalar_config = ScalarConfig(
    show_sidebar=False,
    force_dark_mode_state="dark",
)
 
api = NinjaAPI(
    version="1.0.0",
    title="API Reference",
    description="API Reference for the Scalar Django Ninja Plugin",
    docs=ScalarViewer(scalar_config),
)

For backwards compatibility you can also add the available configuration options as kwargs to ScalarViewer:

from ninja import NinjaAPI
from scalar_ninja import ScalarViewer
 
api = NinjaAPI(
    version="1.0.0",
    title="API Reference",
    description="API Reference for the Scalar Django Ninja Plugin",
    docs=ScalarViewer(show_sidebar=False, force_dark_mode_state="dark"),
    docs_url="/docs/",
)

It's recommended to use ScalarConfig to have a fully typed configuration.

Configuration#

Currently available configuration options are listed below.

Core Configuration#

• openapi_url (default None) - The OpenAPI URL that Scalar should load and use. This is normally done automatically by Django Ninja using the default URL /api/openapi.json. 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.
• agent (default None) - Agent configuration for this source. Object with optional key (string) for production and optional disabled (boolean) to turn off for this source.

Display Options#

• layout (default Layout.MODERN) - Options: Layout
• 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: DocumentDownloadType

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) - Options: SearchHotKey
• 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 []) - List of OpenAPI Server Objects. Each item must have a required url (string) and may have optional description (string) and variables (map). Example: [{"url": "https://api.example.com", "description": "Production"}]
• 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)
• scalar_favicon_url (default "https://django-ninja.dev/img/favicon.png")
• integration (default None)
• theme (default Theme.DEFAULT) - Options: Theme
• agent (default None) - Agent configuration (e.g. AgentConfig(disabled=True) to disable globally). Same shape as per-source agent: optional key, optional disabled.

Agent#

Agent adds an AI chat interface to your API reference. Users can ask questions about your API and get contextual answers based on your OpenAPI document.

• Enabled by default on http://localhost for testing (10 free messages)
• Does not appear in production unless a key is provided
• Requires an Agent key for production deployments
• Your OpenAPI document is uploaded on first message

To enable Agent in production, pass your key. With a single document (no sources):

from scalar_ninja import AgentConfig, ScalarConfig, ScalarViewer
 
api = NinjaAPI(
    docs=ScalarViewer(ScalarConfig(
        openapi_url="/api/openapi.json",
        agent=AgentConfig(key="put-your-agent-scalar-key-here"),
    )),
)

With multiple sources, set the key per source:

from scalar_ninja import AgentConfig, OpenAPISource, ScalarConfig, ScalarViewer
 
api = NinjaAPI(
    docs=ScalarViewer(ScalarConfig(
        sources=[
            OpenAPISource(
                url="https://example.com/openapi.json",
                agent=AgentConfig(key="put-your-agent-scalar-key-here"),
            ),
        ],
    )),
)

To disable Agent entirely:

from scalar_ninja import AgentConfig, ScalarConfig, ScalarViewer
 
api = NinjaAPI(
    docs=ScalarViewer(ScalarConfig(agent=AgentConfig(disabled=True))),
)

DocumentDownloadType#

from scalar_ninja 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

Layout#

from scalar_ninja import Layout
 
# Available options:
Layout.MODERN    # Modern layout
Layout.CLASSIC   # Classic layout

SearchHotKey#

from scalar_ninja import SearchHotKey
 
# All letters from A to Z, e.g.:
SearchHotKey.K   # Use 'K' key for 'Cmd+K' (Mac) / 'Ctrl+K' (Windows/Linux)

Theme#

from scalar_ninja import Theme
 
# Available options:
Theme.DEFAULT   # Default theme
Theme.NONE      # No theme