#[ApiBody]
Expand description
Use this macro to generate serde Serialize
/Deserialize
impls in addition
to an ApiBody
impl that can hand back information about the shape of the
type.
Attributes
Several attributes can be provided to tweak how this works:
#[ApiBody
]: Generatesserde
Serialize and Deserialize impls for this type.#[ApiBody(Serialize,Deserialize
]: The same as above.#[ApiBody(Serialize)]
: Only generate theSerialize
impl for this type.#[ApiBody(Deserialize)]
: Only generate theDeserialize
impl for this type.#[api_body(tag = "foo")]
: Used at the top level, right under#[ApiBody]
, and works the same as#[serde(tag = "foo")]
would.#[api_body(flatten)]
: Used on a struct field whose value is itself a struct, and works the same as#[serde(flatten)]
would.
Notes
Unit enums like enum Foo { A, B, C }
will automatically (de)serialize to one-of the string
literals “A”, “B” or “C”, which slightly differs from how Serde normally apply serialization.
Unit and non-unit variants cannot exist in the same enum for this reason, so that it is
“obvious” how the thing will be (de)serialized.
Example
/// This text will form part of the description of the type
#[ApiBody]
struct Foo {
/// This is a value
value: usize,
bar: Bar
}
/// A 'Bar'y thing
#[ApiBody]
enum Bar {
A {
/// Hello!
hello: String
},
/// B!
B {
/// Bye!
bye: String
}
}
// Here's an example of what the JSON output (because it's more concise) of
// obtaining the type info of `Foo` would look like):
assert_eq!(
serde_json::to_value(Foo::api_body_info()).unwrap(),
json!({
"description": "This text will form part of the description of the type",
"shape": {
"type": "Object",
"keys": {
"value": {
"description": "This is a value",
"shape": { "type": "Number" }
},
"bar": {
"description": "A 'Bar'y thing",
"shape": {
"type": "OneOf",
"values": [
{
"description": "",
"shape": {
"type": "Object",
"keys": {
"kind": {
"description": "Variant tag",
"shape": { "type": "StringLiteral", "literal": "A" }
},
"hello": {
"description": "Hello!",
"shape": { "type": "String" }
}
}
}
},
{
"description": "B!",
"shape": {
"type": "Object",
"keys": {
"kind": {
"description": "Variant tag",
"shape": { "type": "StringLiteral", "literal": "B" }
},
"bye": {
"description": "Bye!",
"shape": { "type": "String" }
}
}
}
}
]
}
},
}
}
})
)