utoipa-swagger-ui

此库实现了通过网页服务器提供 Swagger UI 所必需的样板代码。它作为在 Swagger UI 中提供使用 utoipa 库创建的 OpenAPI 文档的桥梁。

当前实现的支持样板代码包括

• actix-web 版本 >= 4
• rocket 版本 >=0.5
• axum 版本 >=0.7

由于提供 Swagger UI 不依赖于任何框架，因此此库也支持使用其他框架提供 Swagger UI。对于其他框架，需要手动进行更多实现。更多详细信息请参阅 serve 或 示例。

库功能

• actix-web 启用 actix-web 集成，使用预先配置的 SwaggerUI 服务工厂，让用户无需麻烦即可使用 Swagger UI。
• rocket 启用 rocket 集成，使用预先配置的路由来无麻烦地提供 Swagger UI 和 api 文档。
• axum 启用 axum 集成，使用预先配置的路由无麻烦地提供 Swagger UI 和 OpenAPI 规范。
• debug-embed 启用 debug-embed 功能，允许在调试构建中嵌入文件。
• reqwest 根据 SWAGGER_UI_DOWNLOAD_URL 环境变量使用 reqwest 下载 Swagger UI。默认情况下，仅在 Windows 上启用。
• url 默认启用，用于解析和编码下载 URL。
• vendored 启用通过 utoipa-swagger-ui-vendored 库的 vendored Swagger UI。

安装

仅使用原始类型，无需任何样板实现。

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

要使用具有 Swagger UI 的 actix-web 框架，可以这样定义依赖项。

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

注意！ 请记住，您已经在 Cargo.toml 中定义了 utoipa 依赖项。

构建配置

utoipa-swagger-ui 包默认会尝试使用系统中的 curl 包来下载 Swagger UI。可以通过启用 reqwest 功能，选择使用 reqwest 进行下载。在 Windows 系统中，reqwest 功能默认启用。虽然 Reqwest 对于平台无关的构建很有用，但仅仅为了下载一个文件而引入许多不必要的依赖项。如果 SWAGGER_UI_DOWNLOAD_URL 是一个文件路径，则不会发生下载。

以下配置环境变量在构建时可用

• SWAGGER_UI_DOWNLOAD_URL:

  • 如果以 http:// 或 https:// 开头，则是下载 swagger-ui zip 文件的 URL
  • 如果以 file:// 开头，则是复制 swagger-ui zip 文件的文件路径
  • 默认值：https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.12.zip
    • 所有版本：https://github.com/swagger-api/swagger-ui/tags

• SWAGGER_UI_OVERWRITE_FOLDER:

  • 包含要覆盖从 .zip 文件中提取的 swagger-ui 文件的文件夹的绝对路径
  • 通常您可能想要覆盖 index.html

示例

通过 actix-web 提供 Swagger UI 和 api 文档。请参阅示例的完整示例。

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

通过 rocket 提供 Swagger UI 和 api 文档。请参阅示例的完整示例。

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

设置路由以使用 axum 框架提供 Swagger UI。请参阅示例中如何使用 axum 提供 Swagger UI 的完整实现。

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

许可证

根据您的选择，许可协议为 Apache 2.0 或 MIT。

除非您明确表示，否则您提交给包含在此包中的任何贡献，都应双许可，没有任何额外的条款或条件。