Skip to content

feat(openapi): add custom Scalar render options example #4416

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(openapi): add custom Scalar render options example #4416

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/examples/openapi/plugins/scalar_config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,12 @@
from litestar.openapi.plugins import ScalarRenderPlugin

scalar_plugin = ScalarRenderPlugin(version="1.19.5", path="/scalar")

# Example demonstrating custom Scalar render options
# For more configuration options, see: https://guides.scalar.com/scalar/scalar-api-references/configuration
scalar_plugin_with_options = ScalarRenderPlugin(
options={
# Hide the sidebar to give more space to the main content
"showSidebar": False
}
)
11 changes: 0 additions & 11 deletions docs/usage/openapi/ui_plugins.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,17 +242,6 @@ With that, you can preset your clientId or enable PKCE support.
.. literalinclude:: /examples/openapi/plugins/swagger_ui_oauth.py
:language: python

Customizing the OpenAPI UI
Copy link
Member

@JacobCoffee JacobCoffee Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we have removed this section? it needs to be updated to not be so specific to scalar but i think OpenAPI UI can be customized by overriding the default ``css_url`` and ``js_url`` attributes is generic across all our renderers? can probably leave it alone and have another pr to update

Copy link
Member

@JacobCoffee JacobCoffee Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we sortve duplicate it between https://docs.litestar.dev/main/usage/openapi/ui_plugins.html#cdn-and-offline-file-support / https://docs.litestar.dev/main/usage/openapi/ui_plugins.html#customizing-the-openapi-ui 😵‍💫

Copy link
Author

@Umpire2018 Umpire2018 Oct 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we have removed this section?

  1. I prefer to remove this section because i found that we already explained css_url and js_url in https://docs.litestar.dev/main/usage/openapi/ui_plugins.html#configuring-openapi-ui-plugins.

it needs to be updated to not be so specific to scalar

  1. I agree with you. As far as at the https://docs.litestar.dev/main/usage/openapi/ui_plugins.html#customizing-the-openapi-ui part , it would be better to provide different showcases.

css_url and js_url attributes is generic across all our renderers?

  1. Negative. RapidDoc and Redoc don't supprt css_url base on API Reference so far. But maybe it's time to leave some #TODO in code to make it generic.

#cdn-and-offline-file-support part is duplicate.

  1. Maybe we can combine it into #configuring-openapi-ui-plugins part?

--------------------------

Style and behavior of the OpenAPI UI can be customized by overriding the default ``css_url`` and ``js_url`` attributes
on the render plugin class, for example:

.. literalinclude:: /examples/openapi/plugins/scalar_customized.py
:language: python

To learn more about customizing the ``Scalar`` UI, see the `Scalar documentation <https://docs.scalar.com/>`_.

CDN and offline file support
----------------------------

Expand Down
15 changes: 15 additions & 0 deletions tests/examples/test_openapi/test_plugins.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,21 @@ def test_scalar_simple() -> None:
assert "Litestar Example" in resp.text


def test_scalar_render_options() -> None:
from docs.examples.openapi.plugins.scalar_config import scalar_plugin_with_options

openapi_config = OpenAPIConfig(
title="My API",
description="This is the description of my API",
version="0.1.0",
render_plugins=[scalar_plugin_with_options],
)

with create_test_client(route_handlers=[], openapi_config=openapi_config) as client:
resp = client.get("/schema/scalar")
assert '"showSidebar":false' in resp.text


def test_rapidoc_simple() -> None:
from docs.examples.openapi.plugins.rapidoc_simple import app

Expand Down
Loading