Crate utoipa_swagger_ui

This crate implements necessary boiler plate code to serve Swagger UI via web server. It works as a bridge for serving the OpenAPI documentation created with utoipa library in the Swagger UI.

Currently implemented boiler plate for:

• actix-web version >= 4
• rocket version >=0.5
• axum version >=0.7

Serving Swagger UI is framework independent thus this crate also supports serving the Swagger UI with other frameworks as well. With other frameworks there is bit more manual implementation to be done. See more details at serve or examples.

Crate Features

• actix-web Enables actix-web integration with pre-configured SwaggerUI service factory allowing users to use the Swagger UI without a hassle.
• rocket Enables rocket integration with with pre-configured routes for serving the Swagger UI and api doc without a hassle.
• axum Enables axum integration with pre-configured Router serving Swagger UI and OpenAPI specs hassle free.
• debug-embed Enables debug-embed feature on rust_embed crate to allow embedding files in debug builds as well.
• reqwest Use reqwest for downloading Swagger UI according to the SWAGGER_UI_DOWNLOAD_URL environment variable. This is only enabled by default on Windows.
• url Enabled by default for parsing and encoding the download URL.
• vendored Enables vendored Swagger UI via utoipa-swagger-ui-vendored crate.

Install

Use only the raw types without any boiler plate implementation.

[dependencies]
utoipa-swagger-ui = "9"

Enable actix-web framework with Swagger UI you could define the dependency as follows.

[dependencies]
utoipa-swagger-ui = { version = "9", features = ["actix-web"] }

Note! Also remember that you already have defined utoipa dependency in your Cargo.toml

Build Config

Note! utoipa-swagger-ui crate will by default try to use system curl package for downloading the Swagger UI. It can optionally be downloaded with reqwest by enabling reqwest feature. On Windows the reqwest feature is enabled by default. Reqwest can be useful for platform independent builds however bringing quite a few unnecessary dependencies just to download a file. If the SWAGGER_UI_DOWNLOAD_URL is a file path then no downloading will happen.

Tip! Use vendored feature flag to use vendored Swagger UI. This is especially useful for no network environments.

The following configuration env variables are available at build time:

• SWAGGER_UI_DOWNLOAD_URL: Defines the url from where to download the swagger-ui zip file.

  • Current Swagger UI version: https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.14.zip
  • All available Swagger UI versions

• SWAGGER_UI_OVERWRITE_FOLDER: Defines an optional absolute path to a directory containing files to overwrite the Swagger UI files. Typically you might want to overwrite index.html.

Examples

Serve Swagger UI with api doc via actix-web. See full example from examples.

HttpServer::new(move || {
        App::new()
            .service(
                SwaggerUi::new("/swagger-ui/{_:.*}")
                    .url("/api-docs/openapi.json", ApiDoc::openapi()),
            )
    })
    .bind((Ipv4Addr::UNSPECIFIED, 8989)).unwrap()
    .run();

Serve Swagger UI with api doc via rocket. See full example from examples.

#[rocket::launch]
fn rocket() -> Rocket<Build> {
    rocket::build()
        .mount(
            "/",
            SwaggerUi::new("/swagger-ui/<_..>")
                .url("/api-docs/openapi.json", ApiDoc::openapi()),
        )
}

Setup Router to serve Swagger UI with axum framework. See full implementation of how to serve Swagger UI with axum from examples.

 let app = Router::<S>::new()
     .merge(SwaggerUi::new("/swagger-ui")
         .url("/api-docs/openapi.json", ApiDoc::openapi()));

Modules

oauth

Implements Swagger UI oauth configuration options.

Structs

BasicAuth

Basic auth options for Swagger UI. By providing BasicAuth to Config::basic_auth the access to the Swagger UI can be restricted behind given basic authentication.

Config

Object used to alter Swagger UI settings.

SwaggerFile

Represents servable file of Swagger UI. This is used together with serve function to serve Swagger UI files via web server.

SwaggerUiactix-web or rocket or axum

Entry point for serving Swagger UI and api docs in application. It provides builder style chainable configuration methods for configuring api doc urls.

SyntaxHighlight

Represents settings related to syntax highlighting of payloads and cURL commands.

Url

Rust type for Swagger UI url configuration object.

Functions

serve

User friendly way to serve Swagger UI and its content via web server.