diff --git a/core/lib/src/serde/mod.rs b/core/lib/src/serde/mod.rs index 598cc233..13d327a7 100644 --- a/core/lib/src/serde/mod.rs +++ b/core/lib/src/serde/mod.rs @@ -1,4 +1,37 @@ -//! Automatic serialization and deserialization support. +//! Serialization and deserialization support. +//! +//! * JSON support is provided by the [`Json`](json::Json) type. +//! * MessagePack support is provided by the [`MsgPack`](msgpack::MsgPack) type. +//! * UUID support is provided by the [`UUID`](uuid) type. +//! +//! Types implement one or all of [`FromParam`](crate::request::FromParam), +//! [`FromForm`](crate::form::FromForm), [`FromData`](crate::data::FromData), +//! and [`Responder`](crate::response::Responder). +//! +//! ## Deriving `Serialize`, `Deserialize` +//! +//! For convenience, Rocket re-exports `serde`'s `Serialize` and `Deserialize` +//! traits and derive macros from this module. However, due to Rust's limited +//! support for derive macro re-exports, using the re-exported derive macros +//! requires annotating structures with `#[serde(crate = "rocket::serde")]`: +//! +//! ```rust +//! use rocket::serde::{Serialize, Deserialize}; +//! +//! #[derive(Serialize, Deserialize)] +//! #[serde(crate = "rocket::serde")] +//! struct MyStruct { +//! foo: String, +//! } +//! ``` +//! +//! If you'd like to avoid this extra annotation, you must depend on `serde` +//! directly via your crate's `Cargo.toml`: +//! +//! ```toml +//! [dependencies] +//! serde = { version = "1.0", features = ["derive"] } +//! ``` #[doc(inline)] pub use serde::ser::{Serialize, Serializer}; diff --git a/site/guide/4-requests.md b/site/guide/4-requests.md index fa16a95a..4416f235 100644 --- a/site/guide/4-requests.md +++ b/site/guide/4-requests.md @@ -668,6 +668,7 @@ data as JSON. The only condition is that the generic type `T` implements the use rocket::serde::{Deserialize, json::Json}; #[derive(Deserialize)] +#[serde(crate = "rocket::serde")] struct Task<'r> { description: &'r str, complete: bool @@ -677,6 +678,25 @@ struct Task<'r> { fn new(task: Json>) { /* .. */ } ``` +! warning: Using Rocket's `serde` derive re-exports requires a bit more effort. + + For convenience, Rocket re-exports `serde`'s `Serialize` and `Deserialize` + traits and derive macros from `rocket::serde`. However, due to Rust's limited + support for derive macro re-exports, using the re-exported derive macros + requires annotating structures with `#[serde(crate = "rocket::serde")]`. If + you'd like to avoid this extra annotation, you must depend on `serde` directly + via your crate's `Cargo.toml`: + + ` + serde = { version = "1.0", features = ["derive"] } + ` + + We always use the extra annotation in the guide, but you may prefer the + alternative. + +See the [JSON example](@example/serialization/src/json.rs) on GitHub for a +complete example. + ! note: JSON support requires enabling Rocket's `json` feature flag. Rocket intentionally places JSON support, as well support for other data @@ -688,9 +708,6 @@ fn new(task: Json>) { /* .. */ } rocket = { version = "0.5.0-rc.1", features = ["json"] } ` - See the [JSON example](@example/serialization/src/json.rs) on GitHub for a - complete example. - ### Temporary Files The [`TempFile`] data guard streams data directly to a temporary file which can diff --git a/site/guide/5-responses.md b/site/guide/5-responses.md index e511be07..60dd56c3 100644 --- a/site/guide/5-responses.md +++ b/site/guide/5-responses.md @@ -395,6 +395,7 @@ write: use rocket::serde::{Serialize, json::Json}; #[derive(Serialize)] +#[serde(crate = "rocket::serde")] struct Task { /* .. */ } #[get("/todo")] diff --git a/site/guide/9-configuration.md b/site/guide/9-configuration.md index c57ac288..a5d7366b 100644 --- a/site/guide/9-configuration.md +++ b/site/guide/9-configuration.md @@ -354,6 +354,7 @@ fn rocket() -> _ { let figment = rocket.figment(); #[derive(Deserialize)] + #[serde(crate = "rocket::serde")] struct Config { port: u16, custom: Vec, @@ -382,6 +383,7 @@ Because it is common to store configuration in managed state, Rocket provides an # #[macro_use] extern crate rocket; # use rocket::serde::Deserialize; # #[derive(Deserialize)] +# #[serde(crate = "rocket::serde")] # struct Config { # port: u16, # custom: Vec, @@ -457,6 +459,7 @@ use rocket::fairing::AdHoc; use figment::{Figment, Profile, providers::{Format, Toml, Serialized, Env}}; #[derive(Debug, Deserialize, Serialize)] +#[serde(crate = "rocket::serde")] struct Config { app_value: usize, /* and so on.. */ diff --git a/site/tests/Cargo.toml b/site/tests/Cargo.toml index 5a01ce73..03cd22eb 100644 --- a/site/tests/Cargo.toml +++ b/site/tests/Cargo.toml @@ -10,7 +10,6 @@ rocket = { path = "../../core/lib", features = ["secrets"] } [dev-dependencies] rocket = { path = "../../core/lib", features = ["secrets", "json"] } -serde = { version = "1.0", features = ["derive"] } rand = "0.8" figment = { version = "0.10", features = ["toml", "env"] }