plugins

class litestar.openapi.plugins.OpenAPIRenderPlugin[source]

Bases: ABC

Base class for OpenAPI UI render plugins.

__init__(*, path: str | Sequence[str], media_type: MediaType | OpenAPIMediaType = MediaType.HTML, favicon: str = "<link rel='icon' type='image/png' href='https://cdn.jsdelivr.net/gh/litestar-org/branding@main/assets/Branding%20-%20PNG%20-%20Transparent/Badge%20-%20Blue%20and%20Yellow.png'>", style: str = '<style>body { margin: 0; padding: 0 }</style>') → None[source]

Initialize the OpenAPI UI render plugin.

Parameters:

  • path – Path to serve the OpenAPI UI at.

  • media_type – Media type for the handler.

  • favicon – Html <link> tag for the favicon.

  • style – Base styling of the html body.

static render_json(request: Request, openapi_schema: dict[str, Any]) → bytes[source]

Render the OpenAPI schema as JSON.

Parameters:

  • request – The request that triggered the render.

  • openapi_schema – The OpenAPI schema as a dictionary.

Returns:

The rendered JSON.

abstractmethod render(request: Request, openapi_schema: dict[str, Any]) → bytes[source]

Render the OpenAPI UI.

Parameters:

  • request – The request that triggered the render.

  • openapi_schema – The OpenAPI schema as a dictionary.

Returns:

The rendered HTML.

static get_openapi_json_route(request: Request) → str[source]

Get the route for the OpenAPI JSON schema.

Returns:

The route for the OpenAPI JSON schema.

receive_router(router: Router) → None[source]

Receive the router that serves the OpenAPI UI.

Can be used by plugins to additionally configure the router, e.g. to add additional routes.

Parameters:

router – The router that serves the OpenAPI UI.

has_path(path: str) → bool[source]

Check if the plugin has a path.

Parameters:

path – The path to check.

Returns:

True if the plugin has the path, False otherwise.

class litestar.openapi.plugins.RapidocRenderPlugin[source]

Bases: OpenAPIRenderPlugin

Render an OpenAPI schema using Rapidoc.

__init__(*, version: str = '9.3.4', js_url: str | None = None, path: str | Sequence[str] = '/rapidoc', **kwargs: Any) → None[source]

Initialize the OpenAPI UI render plugin.

Parameters:

  • version – Rapidoc version to download from the CDN. If js_url is provided, this is ignored.

  • js_url – Download url for the RapiDoc JS bundle. If not provided, the version will be used to construct the url.

  • path – Path to serve the OpenAPI UI at.

  • **kwargs – Additional arguments to pass to the base class.

render(request: Request, openapi_schema: dict[str, Any]) → bytes[source]

Render an HTML page for Rapidoc.

Note

Override this method to customize the template.

Parameters:

  • request – The request.

  • openapi_schema – The OpenAPI schema as a dictionary.

Returns:

A rendered html string.

class litestar.openapi.plugins.RedocRenderPlugin[source]

Bases: OpenAPIRenderPlugin

Render an OpenAPI schema using Redoc.

__init__(*, version: str = 'latest', js_url: str | None = None, google_fonts: bool = True, path: str | Sequence[str] = '/redoc', **kwargs: Any) → None[source]

Initialize the OpenAPI UI render plugin.

Parameters:

  • version – Redoc version to download from the CDN. If js_url is provided, this is ignored.

  • js_url – Download url for the Redoc JS bundle. If not provided, the version will be used to construct the url.

  • google_fonts – Download google fonts via CDN. Should be set to False when not using a CDN.

  • path – Path to serve the OpenAPI UI at.

  • **kwargs – Additional arguments to pass to the base class.

render(request: Request, openapi_schema: dict[str, Any]) → bytes[source]

Render an HTML page for Redoc.

Note

override this method to customize the template.

Parameters:

  • request – The request.

  • openapi_schema – The OpenAPI schema as a dictionary.

Returns:

A rendered html string.

class litestar.openapi.plugins.ScalarRenderPlugin[source]

Bases: OpenAPIRenderPlugin

Plugin to render an OpenAPI schema using Scalar.

Added in version 2.8.0.

__init__(*, version: str = 'latest', js_url: str | None = None, css_url: str | None = None, path: str | Sequence[str] = '/scalar', options: dict[str, Any] | None = None, **kwargs: Any) → None[source]

Initialize the Scalar OpenAPI UI render plugin.

Parameters:

  • version – Scalar version to download from the CDN. If js_url is provided, this is ignored.

  • js_url – Download url for the Scalar JS bundle. If not provided, the version will be used to construct the url.

  • css_url – Download url for the Scalar CSS bundle. If not provided, the Litestar-provided CSS will be used.

  • path – Path to serve the OpenAPI UI at.

  • options – Scalar configuration options. If not provided the default Scalar configuration will be used.

  • **kwargs – Additional arguments to pass to the base class.

render(request: Request, openapi_schema: dict[str, Any]) → bytes[source]

Render an HTMl page for Scalar.

Note

Override this method to customize the template.

Parameters:

  • request – The request.

  • openapi_schema – The OpenAPI schema as a dictionary.

Returns:

A rendered html string.

render_options() → str[source]

Render options to Scalar configuration.

class litestar.openapi.plugins.StoplightRenderPlugin[source]

Bases: OpenAPIRenderPlugin

Render an OpenAPI schema using StopLight Elements.

__init__(*, version: str = '7.7.18', js_url: str | None = None, css_url: str | None = None, path: str | Sequence[str] = '/elements', **kwargs: Any) → None[source]

Initialize the OpenAPI UI render plugin.

Parameters:

  • version – StopLight Elements version to download from the CDN. If js_url is provided, this is ignored.

  • js_url – Download url for the StopLight Elements JS bundle. If not provided, the version will be used to construct the url.

  • css_url – Download url for the StopLight Elements CSS bundle. If not provided, the version will be used to construct the url.

  • path – Path to serve the OpenAPI UI at.

  • **kwargs – Additional arguments to pass to the base class.

render(request: Request, openapi_schema: dict[str, Any]) → bytes[source]

Render an HTML page for StopLight Elements.

Note

Override this method to customize the template.

Parameters:

  • request – The request.

  • openapi_schema – The OpenAPI schema as a dictionary.

Returns:

A rendered html string.

class litestar.openapi.plugins.SwaggerRenderPlugin[source]

Bases: OpenAPIRenderPlugin

Render an OpenAPI schema using Swagger-UI.

__init__(version: str = '5.18.2', js_url: str | None = None, css_url: str | None = None, standalone_preset_js_url: str | None = None, init_oauth: dict[str, Any] | bytes | None = None, oauth2_redirect_url: str | None = None, path: str | Sequence[str] = '/swagger', **kwargs: Any) → None[source]

Initialize the OpenAPI UI render plugin.

Parameters:

  • version – SwaggerUI version to download from the CDN. If js_url is provided, this is ignored.

  • js_url – Download url for the Swagger UI JS bundle. If not provided, the version will be used to construct the url.

  • css_url – Download url for the Swagger UI CSS bundle. If not provided, the version will be used to construct the url.

  • standalone_preset_js_url – Download url for the Swagger Standalone Preset JS bundle. If not provided, the version will be used to construct the url.

  • init_oauth – JSON to initialize Swagger UI OAuth2 by calling the initOAuth method. Refer to the following URL for details: Swagger-UI.

  • oauth2_redirect_url – Absolute URL of the oauth2-redirect.html page served by Swagger UI. When set, this value is passed as oauth2RedirectUrl in the SwaggerUIBundle configuration, overriding Swagger UI’s default behaviour of computing the URL from the current page location. This is useful when the API is mounted under a sub-path where the auto-computed URL would be wrong.

  • path – Path to serve the OpenAPI UI at.

  • **kwargs – Additional arguments to pass to the base class.

render(request: Request, openapi_schema: dict[str, Any]) → bytes[source]

Render an HTML page for Swagger-UI.

Notes

  • override this method to customize the template.

Parameters:

  • request – The request.

  • openapi_schema – The OpenAPI schema as a dictionary.

Returns:

A rendered html string.

receive_router(router: Router) → None[source]

Receive the router that serves the OpenAPI UI.

Adds a route to serve the OAuth2 redirect page.

Parameters:

router – The router that serves the OpenAPI UI.

static render_oauth2_redirect() → bytes[source]

Render an HTML oauth2-redirect.html page for Swagger-UI.

Note

Override this method to customize the template.

Returns:

A rendered html string.

class litestar.openapi.plugins.YamlRenderPlugin[source]

Bases: OpenAPIRenderPlugin

Render an OpenAPI schema as YAML.

__init__(*, path: str | Sequence[str] = ('/openapi.yaml', '/openapi.yml'), media_type: MediaType | OpenAPIMediaType = OpenAPIMediaType.OPENAPI_YAML, **kwargs: Any) → None[source]

Initialize the OpenAPI UI render plugin.

Parameters:

  • path – Path to serve the OpenAPI UI at.

  • media_type – Media type for the handler.

  • **kwargs – Additional arguments to pass to the base class.

render(request: Request, openapi_schema: dict[str, Any]) → bytes[source]

Render an OpenAPI schema as YAML.

Parameters:

  • request – The request.

  • openapi_schema – The OpenAPI schema as a dictionary.

Returns:

The rendered OpenAPI schema as YAML.