38 releases (stable)
8.0.3 | Oct 23, 2024 |
---|---|
7.1.1-rc.0 | Oct 2, 2024 |
7.1.1-alpha.0 | May 30, 2024 |
6.0.0 | Jan 9, 2024 |
0.1.0-beta1 | Mar 7, 2022 |
#201 in Web programming
224,557 downloads per month
Used in 54 crates
(47 directly)
590KB
7.5K
SLoC
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 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 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 pre-configured routes for serving the Swagger UI and api doc without a hassle.axum
Enablesaxum
integration with pre-configured Router serving Swagger UI and OpenAPI specs hassle free.debug-embed
Enablesdebug-embed
feature onrust_embed
crate to allow embedding files in debug builds as well.reqwest
Usereqwest
for downloading Swagger UI according to theSWAGGER_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 viautoipa-swagger-ui-vendored
crate.
Install
Use only the raw types without any boilerplate implementation.
[dependencies]
utoipa-swagger-ui = "8"
Enable actix-web framework with Swagger UI you could define the dependency as follows.
[dependencies]
utoipa-swagger-ui = { version = "8", features = ["actix-web"] }
Note! Also remember that you already have defined utoipa
dependency in your Cargo.toml
Build Config
[!IMPORTANT]
utoipa-swagger-ui
crate will by default try to use systemcurl
package for downloading the Swagger UI. It can optionally be downloaded withreqwest
by enablingreqwest
feature. Reqwest can be useful for platform independent builds however bringing quite a few unnecessary dependencies just to download a file. If theSWAGGER_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 overwriteindex.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::new()
.merge(SwaggerUi::new("/swagger-ui")
.url("/api-docs/openapi.json", ApiDoc::openapi()));
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
~7–41MB
~639K SLoC