Skip to content

Add customizable page title to utoipa-scalar #1515

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
terror wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Add customizable page title to utoipa-scalar #1515

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f643a28
Add customizable page title to `utoipa-scalar`
terror Jan 27, 2026
17f17e0
Format
terror Feb 23, 2026
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
2 changes: 1 addition & 1 deletion utoipa-scalar/res/scalar.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!doctype html>
<html>
<head>
<title>Scalar</title>
<title>$title</title>
<meta charset="utf-8"/>
<meta
name="viewport"
Expand Down
26 changes: 23 additions & 3 deletions utoipa-scalar/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,10 +65,11 @@
//! * [Configuration options][configuration]
//! * [Themes][themes]
//!
//! The HTML template must contain **`$spec`** variable which will be overridden during
//! [`Scalar::to_html`] execution.
//! The HTML template supports the following variables which will be replaced during
//! [`Scalar::to_html`] execution:
//!
//! * **`$spec`** Will be the [`Spec`] that will be rendered via [Scalar][scalar].
//! * **`$title`** Will be the page title configured via [`Scalar::title`].
//!
//! _**Overriding the HTML template with a custom one.**_
//! ```rust
Expand Down Expand Up @@ -187,6 +188,7 @@ impl<S: Spec> Servable<S> for Scalar<S> {
html: Cow::Borrowed(DEFAULT_HTML),
url: url.into(),
openapi,
title: Cow::Borrowed("Scalar"),
}
}
}
Expand All @@ -205,6 +207,7 @@ pub struct Scalar<S: Spec> {
url: Cow<'static, str>,
html: Cow<'static, str>,
openapi: S,
title: Cow<'static, str>,
}

impl<S: Spec> Scalar<S> {
Expand All @@ -223,6 +226,7 @@ impl<S: Spec> Scalar<S> {
html: Cow::Borrowed(DEFAULT_HTML),
url: Cow::Borrowed("/"),
openapi,
title: Cow::Borrowed("Scalar"),
}
}

Expand All @@ -235,7 +239,7 @@ impl<S: Spec> Scalar<S> {
/// At this point in time, it is not possible to customize the HTML template used by the
/// [`Scalar`] instance.
pub fn to_html(&self) -> String {
self.html.replace(
self.html.replace("$title", &self.title).replace(
"$spec",
&serde_json::to_string(&self.openapi).expect(
"Invalid OpenAPI spec, expected OpenApi, String, &str or serde_json::Value",
Expand All @@ -253,6 +257,22 @@ impl<S: Spec> Scalar<S> {

self
}

/// Set a custom title for the HTML page.
///
/// # Examples
///
/// _**Set custom title for [`Scalar`].**_
/// ```
/// # use utoipa_scalar::Scalar;
/// # use serde_json::json;
/// Scalar::new(json!({"openapi": "3.1.0"})).title("My API");
/// ```
pub fn title<T: Into<Cow<'static, str>>>(mut self, title: T) -> Self {
self.title = title.into();

self
}
}

/// Trait defines OpenAPI spec resource types supported by [`Scalar`].
Expand Down