utoipa-scalar

This crate works as a bridge between utoipa and Scalar OpenAPI visualizer.

Utoipa-scalar provides simple mechanism to transform OpenAPI spec resource to a servable HTML file which can be served via predefined framework integration or used standalone and served manually.

You may find fullsize examples from utoipa's Github repository.

Crate Features

• actix-web Allows serving Scalar via actix-web. version >= 4
• rocket Allows serving Scalar via rocket. version >=0.5
• axum Allows serving Scalar via axum. version >=0.7

Install

Use Scalar only without any boiler plate implementation.

[dependencies]
utoipa-scalar = "0.3"

Enable actix-web integration with Scalar.

[dependencies]
utoipa-scalar = { version = "0.3", features = ["actix-web"] }

Using standalone

Utoipa-scalar can be used standalone as simply as creating a new Scalar instance and then serving it by what ever means available as text/html from http handler in your favourite web framework.

Scalar::to_html method can be used to convert the Scalar instance to a servable html file.

let scalar = Scalar::new(ApiDoc::openapi());

// Then somewhere in your application that handles http operation.
// Make sure you return correct content type `text/html`.
let scalar = move || async {
    scalar.to_html()
};

Customization

Scalar supports customization via [Scalar::custom_html] method which allows overriding the default HTML template with customized one.

See more about configuration options.

• Quick HTML configuration instructions
• Configuration options
• Themes

The HTML template must contain $spec variable which will be overridden during Scalar::to_html execution.

• $spec Will be the Spec that will be rendered via Scalar.

Overriding the HTML template with a custom one.

# use utoipa_redoc::Redoc;
# use utoipa::OpenApi;
# use serde_json::json;
# #[derive(OpenApi)]
# #[openapi()]
# struct ApiDoc;
#
let html = "...";
Redoc::new(ApiDoc::openapi()).custom_html(html);

Examples

Serve Scalar via actix-web framework.

use actix_web::App;
use utoipa_scalar::{Scalar, Servable};

App::new().service(Scalar::with_url("/scalar", ApiDoc::openapi()));

Serve Scalar via rocket framework.

use utoipa_scalar::{Scalar, Servable};

rocket::build()
    .mount(
        "/",
        Scalar::with_url("/scalar", ApiDoc::openapi()),
    );

Serve Scalar via axum framework.

use axum::Router;
use utoipa_scalar::{Scalar, Servable};

let app = Router::<S>::new()
    .merge(Scalar::with_url("/scalar", ApiDoc::openapi()));

Use Scalar to serve OpenAPI spec from url.

Scalar::new(
  "https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml")

Use Scalar to serve custom OpenAPI spec using serde's json!() macro.

Scalar::new(json!({"openapi": "3.1.0"}));

License

Licensed under either of Apache 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, shall be dual licensed, without any additional terms or conditions.