解决 utoipa-swagger-ui 编译失败问题：curl 依赖与替代方案

在使用 Rust 的 utoipa-swagger-ui 库时，开发者可能会遇到编译失败的问题。这个问题的根源在于最新版本的 utoipa-swagger-ui 需要 curl 工具来下载 Swagger UI 资源，而如果系统中没有安装 curl，就会导致编译过程失败。

问题现象

当尝试编译包含 utoipa-swagger-ui 的项目时，会出现类似以下的错误信息：

error: failed to run custom build command for `utoipa-swagger-ui v7.1.0`
thread 'main' panicked at build.rs:181:46:
called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }

从错误日志中可以看到，构建脚本首先尝试使用 reqwest 进行下载，当 reqwest 不可用时，会回退到使用系统 curl 命令。如果系统中没有安装 curl，就会抛出这个错误。

解决方案

utoipa-swagger-ui 提供了两种替代方案来解决这个问题：

1. 使用 reqwest 特性

在项目的 Cargo.toml 文件中，可以启用 reqwest 特性来替代 curl：

[dependencies]
utoipa-swagger-ui = { version = "7.1.0", features = ["reqwest"] }

这种方式会使用 Rust 的 reqwest 库来下载 Swagger UI 资源，而不依赖系统 curl。这是推荐的方式，特别是对于跨平台项目，因为它不依赖外部工具。

2. 使用预打包的 Swagger UI (vendored 特性)

另一种方式是使用 utoipa-swagger-ui 内置的 Swagger UI 资源，这样可以完全避免下载步骤：

[dependencies]
utoipa-swagger-ui = { version = "7.1.0", features = ["vendored"] }

这种方式类似于 utoipa-swagger-ui 6.x 版本之前的行为，它会使用库中已经包含的 Swagger UI 资源，不需要任何网络下载。这对于离线环境或需要确定性构建的场景特别有用。

技术背景

这个问题的出现反映了 Rust 构建脚本的一个常见模式：在构建时获取资源。utoipa-swagger-ui 需要 Swagger UI 的前端资源来提供文档界面，这些资源通常需要从 GitHub 下载。

从 7.x 版本开始，utoipa-swagger-ui 默认尝试使用系统 curl 来下载这些资源，以提高可靠性和减少依赖。然而，这带来了新的系统要求。通过提供 reqwest 和 vendored 两种替代方案，库维护者既保持了灵活性，又为不同使用场景提供了解决方案。

最佳实践建议

1. 对于大多数项目，推荐使用 reqwest 特性，它提供了最好的跨平台兼容性
2. 对于需要离线构建或严格控制依赖的项目，vendored 特性是更好的选择
3. 如果确实需要使用系统 curl，确保构建环境中安装了 curl 工具
4. 可以通过设置 SWAGGER_UI_DOWNLOAD_URL 环境变量来自定义下载源

理解这些选项可以帮助开发者根据项目需求选择最合适的配置方式，确保构建过程的顺利和项目的可维护性。