5 releases
0.2.0 | Oct 14, 2024 |
---|---|
0.2.0-rc.0 | Oct 2, 2024 |
0.2.0-beta.0 | Sep 1, 2024 |
0.2.0-alpha.0 | May 30, 2024 |
0.1.0 | May 5, 2024 |
#1940 in Web programming
43,268 downloads per month
Used in 5 crates
(4 directly)
395KB
6K
SLoC
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
viaactix-web
.version >= 4
- rocket Allows serving
Scalar
viarocket
.version >=0.5
- axum Allows serving
Scalar
viaaxum
.version >=0.7
Install
Use Scalar only without any boiler plate implementation.
[dependencies]
utoipa-scalar = "0.2"
Enable actix-web integration with Scalar.
[dependencies]
utoipa-scalar = { version = "0.2", 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.
The HTML template must contain $spec
variable which will be overridden during
Scalar::to_html
execution.
$spec
Will be theSpec
that will be rendered viaScalar
.
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.
Dependencies
~1–34MB
~536K SLoC