Chore update docs and relax url version

Update docs and relax `url` crate version requirements for Swagger UI.
This commit also ignores some known custom rust cfg args and adds better
error message when building `utoipa-swagger-ui` with Swagger UI that is
downloaded over network via `curl` system package.

Resolves #1000

README.md

@@ -59,54 +59,54 @@ and the `ipa` is _api_ reversed. Aaand... `ipa` is also an awesome type of beer
 
 ## Crate Features
 
-- `yaml`: Enables **serde_yaml** serialization of OpenAPI objects.
-- `actix_extras`: Enhances [actix-web](https://github.com/actix/actix-web/) integration with being able to
+- **`yaml`**: Enables **serde_yaml** serialization of OpenAPI objects.
+- **`actix_extras`**: Enhances [actix-web](https://github.com/actix/actix-web/) integration with being able to
   parse `path`, `path` and `query` parameters from actix web path attribute macros. See
   [docs](https://docs.rs/utoipa/latest/utoipa/attr.path.html#actix_extras-support-for-actix-web) or [examples](./examples) for more details.
-- `rocket_extras`: Enhances [rocket](https://github.com/SergioBenitez/Rocket) framework integration with being
+- **`rocket_extras`**: Enhances [rocket](https://github.com/SergioBenitez/Rocket) framework integration with being
   able to parse `path`, `path` and `query` parameters from rocket path attribute macros. See [docs](https://docs.rs/utoipa/latest/utoipa/attr.path.html#rocket_extras-support-for-rocket)
   or [examples](./examples) for more details.
-- `axum_extras`: Enhances [axum](https://github.com/tokio-rs/axum) framework integration allowing users to use `IntoParams` without
+- **`axum_extras`**: Enhances [axum](https://github.com/tokio-rs/axum) framework integration allowing users to use `IntoParams` without
   defining the `parameter_in` attribute. See [docs](https://docs.rs/utoipa/latest/utoipa/attr.path.html#axum_extras-feature-support-for-axum)
   or [examples](./examples) for more details.
-- `debug`: Add extra traits such as debug traits to openapi definitions and elsewhere.
-- `chrono`: Add support for [chrono](https://crates.io/crates/chrono) `DateTime`, `Date`, `NaiveDate`, `NaiveDateTime`, `NaiveTime` and `Duration`
+- **`debug`**: Add extra traits such as debug traits to openapi definitions and elsewhere.
+- **`chrono`**: Add support for [chrono](https://crates.io/crates/chrono) `DateTime`, `Date`, `NaiveDate`, `NaiveDateTime`, `NaiveTime` and `Duration`
   types. By default these types are parsed to `string` types with additional `format` information.
   `format: date-time` for `DateTime` and `NaiveDateTime` and `format: date` for `Date` and `NaiveDate` according
   [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) as `ISO-8601`. To
   override default `string` representation users have to use `value_type` attribute to override the type.
   See [docs](https://docs.rs/utoipa/latest/utoipa/derive.ToSchema.html) for more details.
-- `time`: Add support for [time](https://crates.io/crates/time) `OffsetDateTime`, `PrimitiveDateTime`, `Date`, and `Duration` types.
+- **`time`**: Add support for [time](https://crates.io/crates/time) `OffsetDateTime`, `PrimitiveDateTime`, `Date`, and `Duration` types.
   By default these types are parsed as `string`. `OffsetDateTime` and `PrimitiveDateTime` will use `date-time` format. `Date` will use
   `date` format and `Duration` will not have any format. To override default `string` representation users have to use `value_type` attribute
   to override the type. See [docs](https://docs.rs/utoipa/latest/utoipa/derive.ToSchema.html) for more details.
-- `decimal`: Add support for [rust_decimal](https://crates.io/crates/rust_decimal) `Decimal` type. **By default**
+- **`decimal`**: Add support for [rust_decimal](https://crates.io/crates/rust_decimal) `Decimal` type. **By default**
   it is interpreted as `String`. If you wish to change the format you need to override the type.
   See the `value_type` in [component derive docs](https://docs.rs/utoipa/latest/utoipa/derive.ToSchema.html).
-- `decimal_float`: Add support for [rust_decimal](https://crates.io/crates/rust_decimal) `Decimal` type. **By default**
+- **`decimal_float`**: Add support for [rust_decimal](https://crates.io/crates/rust_decimal) `Decimal` type. **By default**
   it is interpreted as `Number`. This feature is mutually exclusive with **decimal** and allow to change the default type used in your
   documentation for `Decimal` much like `serde_with_float` feature exposed by rust_decimal.
-- `uuid`: Add support for [uuid](https://github.com/uuid-rs/uuid). `Uuid` type will be presented as `String` with
+- **`uuid`**: Add support for [uuid](https://github.com/uuid-rs/uuid). `Uuid` type will be presented as `String` with
   format `uuid` in OpenAPI spec.
-- `ulid`: Add support for [ulid](https://github.com/dylanhart/ulid-rs). `Ulid` type will be presented as `String` with
+- **`ulid`**: Add support for [ulid](https://github.com/dylanhart/ulid-rs). `Ulid` type will be presented as `String` with
   format `ulid` in OpenAPI spec.
-- `url`: Add support for [url](https://github.com/servo/rust-url). `Url` type will be presented as `String` with
+- **`url`**: Add support for [url](https://github.com/servo/rust-url). `Url` type will be presented as `String` with
   format `uri` in OpenAPI spec.
-- `smallvec`: Add support for [smallvec](https://crates.io/crates/smallvec). `SmallVec` will be treated as `Vec`.
-- `openapi_extensions`: Adds traits and functions that provide extra convenience functions.
+- **`smallvec`**: Add support for [smallvec](https://crates.io/crates/smallvec). `SmallVec` will be treated as `Vec`.
+- **`openapi_extensions`**: Adds traits and functions that provide extra convenience functions.
   See the [`request_body` docs](https://docs.rs/utoipa/latest/utoipa/openapi/request_body) for an example.
-- `repr`: Add support for [repr_serde](https://github.com/dtolnay/serde-repr)'s `repr(u*)` and `repr(i*)` attributes to unit type enums for
+- **`repr`**: Add support for [repr_serde](https://github.com/dtolnay/serde-repr)'s `repr(u*)` and `repr(i*)` attributes to unit type enums for
   C-like enum representation. See [docs](https://docs.rs/utoipa/latest/utoipa/derive.ToSchema.html) for more details.
-- `preserve_order`: Preserve order of properties when serializing the schema for a component.
+- **`preserve_order`**: Preserve order of properties when serializing the schema for a component.
   When enabled, the properties are listed in order of fields in the corresponding struct definition.
   When disabled, the properties are listed in alphabetical order.
-- `preserve_path_order`: Preserve order of OpenAPI Paths according to order they have been
+- **`preserve_path_order`**: Preserve order of OpenAPI Paths according to order they have been
   introduced to the `#[openapi(paths(...))]` macro attribute. If disabled the paths will be
   ordered in alphabetical order.
-- `indexmap`: Add support for [indexmap](https://crates.io/crates/indexmap). When enabled `IndexMap` will be rendered as a map similar to
+- **`indexmap`**: Add support for [indexmap](https://crates.io/crates/indexmap). When enabled `IndexMap` will be rendered as a map similar to
   `BTreeMap` and `HashMap`.
-- `non_strict_integers`: Add support for non-standard integer formats `int8`, `int16`, `uint8`, `uint16`, `uint32`, and `uint64`.
-- `rc_schema`: Add `ToSchema` support for `Arc<T>` and `Rc<T>` types. **Note!** serde `rc` feature flag must be enabled separately to allow
+- **`non_strict_integers`**: Add support for non-standard integer formats `int8`, `int16`, `uint8`, `uint16`, `uint32`, and `uint64`.
+- **`rc_schema`**: Add `ToSchema` support for `Arc<T>` and `Rc<T>` types. **Note!** serde `rc` feature flag must be enabled separately to allow
   serialization and deserialization of `Arc<T>` and `Rc<T>` types. See more about [serde feature flags](https://serde.rs/feature-flags.html).
 
 Utoipa implicitly has partial support for `serde` attributes. See [docs](https://docs.rs/utoipa/latest/utoipa/derive.ToSchema.html#partial-serde-attributes-support) for more details.

utoipa-gen/Cargo.toml

@@ -59,3 +59,6 @@ rc_schema = []
 
 # EXPERIEMENTAL! use with cauntion
 auto_into_responses = []
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(doc_cfg)'] }

utoipa-rapidoc/Cargo.toml

@@ -22,3 +22,6 @@ utoipa = { version = "5.0.0-alpha", path = "../utoipa" }
 actix-web = { version = "4", optional = true, default-features = false }
 rocket = { version = "0.5", features = ["json"], optional = true }
 axum = { version = "0.7", default-features = false, features = ["json"], optional = true }
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(doc_cfg)'] }

utoipa-redoc/Cargo.toml

@@ -22,3 +22,6 @@ utoipa = { version = "5.0.0-alpha", path = "../utoipa" }
 actix-web = { version = "4", optional = true, default-features = false }
 rocket = { version = "0.5", features = ["json"], optional = true }
 axum = { version = "0.7", default-features = false, optional = true }
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(doc_cfg)'] }

utoipa-scalar/Cargo.toml

@@ -22,3 +22,6 @@ utoipa = { version = "5.0.0-alpha.0", path = "../utoipa" }
 actix-web = { version = "4", optional = true, default-features = false }
 rocket = { version = "0.5", features = ["json"], optional = true }
 axum = { version = "0.7", default-features = false, optional = true }
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(doc_cfg)'] }

utoipa-swagger-ui/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "utoipa-swagger-ui"
 description = "Swagger UI for utoipa"
-version = "7.1.1-alpha.1"
+version = "7.1.1-alpha.2"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
@@ -49,7 +49,7 @@ reqwest = { version = "0.12", features = [
     "blocking",
     "rustls-tls",
 ], default-features = false, optional = true }
-url = { version = "2.5", optional = true }
+url = { version = "2", optional = true }
 utoipa-swagger-ui-vendored = { version = "0.1", path = "../utoipa-swagger-ui-vendored", optional = true }
 
 # Windows is forced to use reqwest to download the Swagger UI.
@@ -59,3 +59,6 @@ reqwest = { version = "0.12", features = [
     "rustls-tls",
 ], default-features = false }
 utoipa-swagger-ui-vendored = { version = "0.1", path = "../utoipa-swagger-ui-vendored", optional = true }
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(doc_cfg)'] }

utoipa-swagger-ui/README.md

@@ -22,18 +22,18 @@ more details at [serve](https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_
 
 ## Crate Features
 
-* **actix-web** Enables actix-web integration with pre-configured SwaggerUI service factory allowing
+* **`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
+* **`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
+* **`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
+* **`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
+* **`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.
+* **`url`** Enabled by default for parsing and encoding the download URL.
+* **`vendored`** Enables vendored Swagger UI via `utoipa-swagger-ui-vendored` crate.
 
 ## Install
 
@@ -55,25 +55,26 @@ utoipa-swagger-ui = { version = "7", features = ["actix-web"] }
 
 ## 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._
+> [!IMPORTANT]
+> _`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:
+> [!TIP]
+> Use **`vendored`** feature flag to use vendored Swagger UI. This is especially useful for no network 
+> environments.
 
-* `SWAGGER_UI_DOWNLOAD_URL`:
+**The following configuration env variables are available at build time:**
 
-  * 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_DOWNLOAD_URL`: Defines the url from where to download the swagger-ui zip file.
 
-* `SWAGGER_UI_OVERWRITE_FOLDER`:
+   * Current Swagger UI version: <https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.12.zip>
+   * [All available Swagger UI versions](https://github.com/swagger-api/swagger-ui/tags)
 
-  * 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`
+ * `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
 

utoipa-swagger-ui/build.rs

@@ -178,7 +178,8 @@ fn get_zip_archive(url: &str, target_dir: &str) -> SwaggerZip {
         // with http protocol we update when the 'SWAGGER_UI_DOWNLOAD_URL' changes
         println!("cargo:rerun-if-env-changed={SWAGGER_UI_DOWNLOAD_URL}");
 
-        download_file(url, zip_path.clone()).unwrap();
+        download_file(url, zip_path.clone())
+            .unwrap_or_else(|error| panic!("failed to download Swagger UI: {error}"));
         let swagger_ui_zip =
             File::open([target_dir, &zip_filename].iter().collect::<PathBuf>()).unwrap();
         let zip = ZipArchive::new(swagger_ui_zip).expect("failed to open downloaded Swagger UI");
@@ -312,6 +313,13 @@ fn download_file_curl<T: AsRef<Path>>(url: &str, target_dir: T) -> Result<(), Bo
                 ))
             }
         })
+        .map_err(|error| {
+            if error.kind() == io::ErrorKind::NotFound {
+                io::Error::new(error.kind(), "`curl` command not found".to_string())
+            } else {
+                error
+            }
+        })
         .map_err(Box::new)?)
 }
 

utoipa-swagger-ui/src/lib.rs

@@ -19,18 +19,18 @@
 //!
 //! # Crate Features
 //!
-//! * **actix-web** Enables `actix-web` integration with pre-configured SwaggerUI service factory allowing
+//! * **`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
+//! * **`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
+//! * **`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
+//! * **`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
+//! * **`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.
+//! * **`url`** Enabled by default for parsing and encoding the download URL.
+//! * **`vendored`** Enables vendored Swagger UI via `utoipa-swagger-ui-vendored` crate.
 //!
 //! # Install
 //!
@@ -50,24 +50,32 @@
 //!
 //! ## Build Config
 //!
-//! _`utoipa-swagger-ui` crate will by default try to use system `curl` package for downloading the Swagger UI. It
+//! <div class="warning">
+//!
+//! **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._
 //!
-//! The following configuration env variables are available at build time:
+//! </div>
+//!
+//! <div class="warning">
+//!
+//! **Tip!** Use **`vendored`** feature flag to use vendored Swagger UI. This is especially useful for no network 
+//! environments.
+//!
+//! </div>
 //!
-//! * `SWAGGER_UI_DOWNLOAD_URL`:
+//! **The following configuration env variables are available at build time:**
 //!
-//!   * the url from where to download the swagger-ui zip 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_DOWNLOAD_URL`: Defines the url from where to download the swagger-ui zip file.
 //!
-//! * `SWAGGER_UI_OVERWRITE_FOLDER`:
+//!   * Current Swagger UI version: <https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.12.zip>
+//!   * [All available Swagger UI versions](https://github.com/swagger-api/swagger-ui/tags)
 //!
-//!   * absolute path to a folder containing files to overwrite the default swagger-ui files
-//!   * typically you might want to overwrite `index.html`
+//! * `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
 //!

utoipa/Cargo.toml

@@ -59,3 +59,6 @@ assert-json-diff = "2"
 [package.metadata.docs.rs]
 features = ["actix_extras", "non_strict_integers", "openapi_extensions", "uuid", "ulid", "url", "yaml"]
 rustdoc-args = ["--cfg", "doc_cfg"]
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(doc_cfg)'] }