Attribute Macro seamless::ApiBody

#[ApiBody]

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]: Generates serde Serialize and Deserialize impls for this type.
• #[ApiBody(Serialize,Deserialize]: The same as above.
• #[ApiBody(Serialize)]: Only generate the Serialize impl for this type.
• #[ApiBody(Deserialize)]: Only generate the Deserialize 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" }
                                        }
                                    }
                                }
                            }
                        ]
                    }
                },
            }
        }
    })
)