Derive Macro Responder

#[derive(Responder)]
{
    // Attributes available to this derive:
    #[response]
}

Derive for the Responder trait.

The Responder derive can be applied to enums and structs with named fields. When applied to enums, variants must have at least one field. When applied to structs, the struct must have at least one field.

#[derive(Responder)]
enum MyResponderA {
    A(String),
    B(File, ContentType),
}

#[derive(Responder)]
struct MyResponderB {
    inner: OtherResponder,
    header: ContentType,
}

The derive generates an implementation of the Responder trait for the decorated enum or structure. The derive uses the first field of a variant or structure to generate a Response. As such, the type of the first field must implement Responder. The remaining fields of a variant or structure are set as headers in the produced Response using Response::set_header(). As such, every other field (unless explicitly ignored, explained next) must implement Into<Header>.

Except for the first field, fields decorated with #[response(ignore)] are ignored by the derive:

#[derive(Responder)]
enum MyResponder {
    A(String),
    B(File, ContentType, #[response(ignore)] Other),
}

#[derive(Responder)]
struct MyOtherResponder {
    inner: NamedFile,
    header: ContentType,
    #[response(ignore)]
    other: Other,
}

Decorating the first field with #[response(ignore)] has no effect.

Additionally, the response attribute can be used on named structures and enum variants to override the status and/or content-type of the Response produced by the generated implementation. The response attribute used in these positions has the following grammar:

response := parameter (',' parameter)?

parameter := 'status' '=' STATUS
           | 'content_type' '=' CONTENT_TYPE

STATUS := unsigned integer >= 100 and < 600
CONTENT_TYPE := string literal, as defined by Rust, identifying a valid
                Content-Type, as defined by Rocket

It can be used as follows:

#[derive(Responder)]
enum Error {
    #[response(status = 500, content_type = "json")]
    A(String),
    #[response(status = 404)]
    B(NamedFile, ContentType),
}

#[derive(Responder)]
#[response(status = 400)]
struct MyResponder {
    inner: InnerResponder,
    header: ContentType,
    #[response(ignore)]
    other: Other,
}

The attribute accepts two key/value pairs: status and content_type. The value of status must be an unsigned integer representing a valid status code. The Response produced from the generated implementation will have its status overriden to this value.

The value of content_type must be a valid media-type in top/sub form or shorthand form. Examples include:

• "text/html"
• "application/x-custom"
• "html"
• "json"
• "plain"
• "binary"

See ContentType::parse_flexible() for a full list of available shorthands. The Response produced from the generated implementation will have its content-type overriden to this value.