Crate utoipa_rapidoc

source
Expand description

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

Utoipa-rapidoc 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 RapiDoc via actix-web.
  • rocket Allows serving RapiDoc via rocket.
  • axum Allows serving RapiDoc via axum.

§Install

Use RapiDoc only without any boiler plate implementation.

[dependencies]
utoipa-rapidoc = "4"

Enable actix-web integration with RapiDoc.

[dependencies]
utoipa-rapidoc = { version = "4", features = ["actix-web"] }

§Using standalone

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

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

let rapidoc = RapiDoc::new("/api-docs/openapi.json");

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

§Customization

Utoipa-rapidoc can be customized and configured only via RapiDoc::custom_html method. This method empowers users to use a custom HTML template to modify the looks of the RapiDoc UI.

The template should contain $specUrl variable which will be replaced with user defined OpenAPI spec url provided with RapiDoc::new function when creating a new RapiDoc instance. Variable will be replaced during RapiDoc::to_html function execution.

Overriding the HTML template with a custom one.

let html = "...";
RapiDoc::new("/api-docs/openapi.json").custom_html(html);

§Examples

Serve RapiDoc via actix-web framework.

use actix_web::App;
use utoipa_rapidoc::RapiDoc;

App::new()
    .service(
        RapiDoc::with_openapi("/api-docs/openapi.json", ApiDoc::openapi()).path("/rapidoc")
    );

Serve RapiDoc via rocket framework.

use utoipa_rapidoc::RapiDoc;

rocket::build()
    .mount(
        "/",
        RapiDoc::with_openapi("/api-docs/openapi.json", ApiDoc::openapi()).path("/rapidoc"),
    );

Serve RapiDoc via axum framework.

use axum::Router;
use utoipa_rapidoc::RapiDoc;

let app = Router::<S>::new()
    .merge(
        RapiDoc::with_openapi("/api-docs/openapi.json", ApiDoc::openapi()).path("/rapidoc")
    );

Structs§