Attribute Macro ruma_common::api::response

source ·
#[response]
Available on crate feature api only.
Expand description

Generates OutgoingResponse and IncomingResponse implementations.

The OutgoingRequest impl is feature-gated behind cfg(feature = "client"). The IncomingRequest impl is feature-gated behind cfg(feature = "server").

The generated code expects a METADATA constant of type Metadata to be in scope.

§Attributes

To declare which part of the request a field belongs to:

  • #[ruma_api(header = HEADER_NAME)]: Fields with this attribute will be treated as HTTP headers on the response. The value must implement Display. Generally this is a String. The attribute value shown above as HEADER_NAME must be a header name constant from http::header, e.g. CONTENT_TYPE.
  • No attribute: Fields without an attribute are part of the body. They can use #[serde] attributes to customize (de)serialization.
  • #[ruma_api(body)]: Use this if multiple endpoints should share a response body type, or the response body is better expressed as an enum rather than a struct. The value of the field will be used as the JSON body (rather than being a field in the response body object).
  • #[ruma_api(raw_body)]: Like body in that the field annotated with it represents the entire response body, but this attribute is for endpoints where the body can be anything, not just JSON. The field type must be Vec<u8>.

§Examples

pub mod do_a_thing {
    use ruma_common::{api::response, OwnedRoomId};

    // const METADATA: Metadata = metadata! { ... };

    // #[request]
    // pub struct Request { ... }

    #[response]
    pub struct Response {
        #[serde(skip_serializing_if = "Option::is_none")]
        pub foo: Option<String>,
    }
}

pub mod download_file {
    use http::header::CONTENT_TYPE;
    use ruma_common::api::response;

    // const METADATA: Metadata = metadata! { ... };

    // #[request]
    // pub struct Request { ... }

    #[response]
    pub struct Response {
        #[ruma_api(header = CONTENT_TYPE)]
        pub content_type: String,

        #[ruma_api(raw_body)]
        pub file: Vec<u8>,
    }
}

⚠ If this is the only documentation you see, please navigate to the docs for ruma_common::api::response, where actual documentation can be found.