# utoipa-swagger-ui
[](https://github.com/juhaku/utoipa/actions/workflows/build.yaml)
[](https://crates.io/crates/utoipa-swagger-ui)
[](https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_ui/)
This crate implements necessary boilerplate code to serve Swagger UI via web server. It
works as a bridge for serving the OpenAPI documentation created with
[utoipa](https://docs.rs/utoipa/) library in the Swagger UI.
**Currently implemented boilerplate 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 a bit more manual implementation to be done. See
more details at [serve](https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_ui/fn.serve.html) or
[examples](https://github.com/juhaku/utoipa/tree/master/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 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 accoring 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 boilerplate implementation.
```toml
[dependencies]
utoipa-swagger-ui = "7"
```
Enable actix-web framework with Swagger UI you could define the dependency as follows.
```toml
[dependencies]
utoipa-swagger-ui = { version = "7", features = ["actix-web"] }
```
**Note!** Also remember that you already have defined `utoipa` dependency in your `Cargo.toml`
## Build Config
_`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._
The following configuration env variables are available at build time:
* `SWAGGER_UI_DOWNLOAD_URL`:
* the url from where to download the swagger-ui zip file if starts with `http://` or `https://`
* the file path from where to copy the swagger-ui zip file if starts with `file://`
* default value: <https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.12.zip>
* all versions: <https://github.com/swagger-api/swagger-ui/tags>
* `SWAGGER_UI_OVERWRITE_FOLDER`:
* absolute path to a folder containing files to overwrite the swagger-ui files extracted from the `.zip` file
* typically you might want to overwrite `index.html`
## Examples
Serve Swagger UI with api doc via **`actix-web`**. See full example from [examples](https://github.com/juhaku/utoipa/tree/master/examples/todo-actix).
```rust
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](https://github.com/juhaku/utoipa/tree/master/examples/rocket-todo).
```rust
#[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](https://github.com/juhaku/utoipa/tree/master/examples/todo-axum).
```rust
let app = Router::new()
.merge(SwaggerUi::new("/swagger-ui")
.url("/api-docs/openapi.json", ApiDoc::openapi()));
```
## License
Licensed under either of [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-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.