From e84d563b261f7e32c882db2383fc7b36c1b0cf9a Mon Sep 17 00:00:00 2001 From: Jonas Platte Date: Wed, 25 Oct 2023 23:37:19 +0200 Subject: [PATCH] Improve documentation of axum::Form (#2289) --- .github/workflows/CI.yml | 2 +- axum-extra/Cargo.toml | 2 +- axum-extra/README.md | 2 +- axum-extra/src/typed_header.rs | 2 +- axum-macros/Cargo.toml | 2 +- axum-macros/README.md | 2 +- axum/CHANGELOG.md | 2 +- axum/Cargo.toml | 2 +- axum/README.md | 2 +- axum/src/extract/path/mod.rs | 2 +- axum/src/form.rs | 22 ++++++++++++++++------ 11 files changed, 26 insertions(+), 16 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index db6e5eab..79ce2112 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -2,7 +2,7 @@ name: CI env: CARGO_TERM_COLOR: always - MSRV: '1.63' + MSRV: '1.65' on: push: diff --git a/axum-extra/Cargo.toml b/axum-extra/Cargo.toml index 710d1199..828db3f5 100644 --- a/axum-extra/Cargo.toml +++ b/axum-extra/Cargo.toml @@ -2,7 +2,7 @@ categories = ["asynchronous", "network-programming", "web-programming"] description = "Extra utilities for axum" edition = "2021" -rust-version = "1.63" +rust-version = "1.65" homepage = "https://github.com/tokio-rs/axum" keywords = ["http", "web", "framework"] license = "MIT" diff --git a/axum-extra/README.md b/axum-extra/README.md index cef56898..d94414ce 100644 --- a/axum-extra/README.md +++ b/axum-extra/README.md @@ -14,7 +14,7 @@ This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in ## Minimum supported Rust version -axum-extra's MSRV is 1.63. +axum-extra's MSRV is 1.65. ## Getting Help diff --git a/axum-extra/src/typed_header.rs b/axum-extra/src/typed_header.rs index 814b1a68..aa89e81d 100644 --- a/axum-extra/src/typed_header.rs +++ b/axum-extra/src/typed_header.rs @@ -105,7 +105,7 @@ where } } -/// Rejection used for [`TypedHeader`](TypedHeader). +/// Rejection used for [`TypedHeader`]. #[cfg(feature = "typed-header")] #[derive(Debug)] pub struct TypedHeaderRejection { diff --git a/axum-macros/Cargo.toml b/axum-macros/Cargo.toml index ef98c51b..dc74f519 100644 --- a/axum-macros/Cargo.toml +++ b/axum-macros/Cargo.toml @@ -2,7 +2,7 @@ categories = ["asynchronous", "network-programming", "web-programming"] description = "Macros for axum" edition = "2021" -rust-version = "1.63" +rust-version = "1.65" homepage = "https://github.com/tokio-rs/axum" keywords = ["axum"] license = "MIT" diff --git a/axum-macros/README.md b/axum-macros/README.md index e411e417..79a8752d 100644 --- a/axum-macros/README.md +++ b/axum-macros/README.md @@ -14,7 +14,7 @@ This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in ## Minimum supported Rust version -axum-macros's MSRV is 1.63. +axum-macros's MSRV is 1.65. ## Getting Help diff --git a/axum/CHANGELOG.md b/axum/CHANGELOG.md index 57474c53..7294549c 100644 --- a/axum/CHANGELOG.md +++ b/axum/CHANGELOG.md @@ -61,7 +61,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **fixed:** Fix `.source()` of composite rejections ([#2030]) - **fixed:** Allow unreachable code in `#[debug_handler]` ([#2014]) - **change:** Update tokio-tungstenite to 0.19 ([#2021]) -- **change:** axum's MSRV is now 1.63 ([#2021]) +- **change:** axum's MSRV is now 1.65 ([#2021]) - **added:** Implement `Handler` for `T: IntoResponse` ([#2140]) - **added:** Implement `IntoResponse` for `(R,) where R: IntoResponse` ([#2143]) - **changed:** For SSE, add space between field and value for compatibility ([#2149]) diff --git a/axum/Cargo.toml b/axum/Cargo.toml index e0062a09..acdce9bc 100644 --- a/axum/Cargo.toml +++ b/axum/Cargo.toml @@ -4,7 +4,7 @@ version = "0.6.16" categories = ["asynchronous", "network-programming", "web-programming::http-server"] description = "Web framework that focuses on ergonomics and modularity" edition = "2021" -rust-version = "1.63" +rust-version = "1.65" homepage = "https://github.com/tokio-rs/axum" keywords = ["http", "web", "framework"] license = "MIT" diff --git a/axum/README.md b/axum/README.md index a97b734c..0b55d6ab 100644 --- a/axum/README.md +++ b/axum/README.md @@ -112,7 +112,7 @@ This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in ## Minimum supported Rust version -axum's MSRV is 1.63. +axum's MSRV is 1.65. ## Examples diff --git a/axum/src/extract/path/mod.rs b/axum/src/extract/path/mod.rs index dd9acccc..8df392a8 100644 --- a/axum/src/extract/path/mod.rs +++ b/axum/src/extract/path/mod.rs @@ -348,7 +348,7 @@ impl fmt::Display for ErrorKind { } } -/// Rejection type for [`Path`](super::Path) if the captured routes params couldn't be deserialized +/// Rejection type for [`Path`] if the captured routes params couldn't be deserialized /// into the expected type. #[derive(Debug)] pub struct FailedToDeserializePathParams(PathDeserializationError); diff --git a/axum/src/form.rs b/axum/src/form.rs index cd30f0e8..5f42b303 100644 --- a/axum/src/form.rs +++ b/axum/src/form.rs @@ -12,9 +12,18 @@ use serde::Serialize; /// /// # As extractor /// -/// If used as an extractor `Form` will deserialize the query parameters for `GET` and `HEAD` -/// requests and `application/x-www-form-urlencoded` encoded request bodies for other methods. It -/// supports any type that implements [`serde::Deserialize`]. +/// If used as an extractor, `Form` will deserialize form data from the request, +/// specifically: +/// +/// - If the request has a method of `GET` or `HEAD`, the form data will be read +/// from the query string (same as with [`Query`]) +/// - If the request has a different method, the form will be read from the body +/// of the request. It must have a `content-type` of +/// `application/x-www-form-urlencoded` for this to work. If you want to parse +/// `multipart/form-data` request bodies, use [`Multipart`] instead. +/// +/// This matches how HTML forms are sent by browsers by default. +/// In both cases, the inner type `T` must implement [`serde::Deserialize`]. /// /// ⚠️ Since parsing form data might require consuming the request body, the `Form` extractor must be /// *last* if there are multiple extractors in a handler. See ["the order of @@ -37,11 +46,11 @@ use serde::Serialize; /// } /// ``` /// -/// Note that `Content-Type: multipart/form-data` requests are not supported. Use [`Multipart`] -/// instead. -/// /// # As response /// +/// `Form` can also be used to encode any type that implements +/// [`serde::Serialize`] as `application/x-www-form-urlencoded` +/// /// ```rust /// use axum::Form; /// use serde::Serialize; @@ -56,6 +65,7 @@ use serde::Serialize; /// } /// ``` /// +/// [`Query`]: crate::extract::Query /// [`Multipart`]: crate::extract::Multipart #[cfg_attr(docsrs, doc(cfg(feature = "form")))] #[derive(Debug, Clone, Copy, Default)]