utoipa-redoc

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

Utoipa-redoc 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 Redoc via actix-web. version >= 4
• rocket Allows serving Redoc via rocket. version >=0.5
• axum Allows serving Redoc via axum. version >=0.7

Install

Use Redoc only without any boiler plate implementation.

[dependencies]
utoipa-redoc = "3"

Enable actix-web integration with Redoc.

[dependencies]
utoipa-redoc = { version = "3", features = ["actix-web"] }

Using standalone

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

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

let redoc = Redoc::new(ApiDoc::openapi());

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

Customization

Utoipa-redoc enables full customizaton support for Redoc according to what can be customized by modifying the HTML template and configuration options.

The default HTML template can be fully overridden to ones liking with Redoc::custom_html method. The HTML template must contain $spec and $config variables which are replaced during Redoc::to_html execution.

• $spec Will be the Spec that will be rendered via Redoc.
• $config Will be the current Config. By default this is EmptyConfig.

Overiding the HTML template with a custom one.

let html = "...";
Redoc::new(ApiDoc::openapi()).custom_html(html);

Configuration

Redoc can be configured with JSON either inlined with the Redoc declaration or loaded from user defined file with FileConfig.

• All supported Redoc configuration options.

Inlining the configuration.

Redoc::with_config(ApiDoc::openapi(), || json!({ "disableSearch": true }));

Using FileConfig.

Redoc::with_config(ApiDoc::openapi(), FileConfig);

Read more details in Config.

Examples

Serve Redoc via actix-web framework.

use actix_web::App;
use utoipa_redoc::{Redoc, Servable};

App::new().service(Redoc::with_url("/redoc", ApiDoc::openapi()));

Serve Redoc via rocket framework.

use utoipa_redoc::{Redoc, Servable};

rocket::build()
    .mount(
        "/",
        Redoc::with_url("/redoc", ApiDoc::openapi()),
    );

Serve Redoc via axum framework.

use axum::Router;
use utoipa_redoc::{Redoc, Servable};

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

Use Redoc to serve OpenAPI spec from url.

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

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

Redoc::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.