Derive Macro IntoResponses

#[derive(IntoResponses)]
{
    // Attributes available to this derive:
    #[response]
    #[to_schema]
    #[ref_response]
    #[to_response]
}

Generate responses with status codes what can be attached to the utoipa::path.

This is #[derive] implementation of IntoResponses trait. IntoResponses can be used to decorate structs and enums to generate response maps that can be used in utoipa::path. If struct is decorated with IntoResponses it will be used to create a map of responses containing single response. Decorating enum with IntoResponses will create a map of responses with a response for each variant of the enum.

Named field struct decorated with IntoResponses will create a response with inlined schema generated from the body of the struct. This is a conveniency which allows users to directly create responses with schemas without first creating a separate response type.

Unit struct behaves similarly to then named field struct. Only difference is that it will create a response without content since there is no inner fields.

Unnamed field struct decorated with IntoResponses will by default create a response with referenced schema if field is object or schema if type is primitive type. #[to_schema] attribute at field of unnamed struct can be used to inline the schema if type of the field implements ToSchema trait. Alternatively #[to_response] and #[ref_response] can be used at field to either reference a reusable response or inline a reusable response. In both cases the field type is expected to implement ToResponse trait.

Enum decorated with IntoResponses will create a response for each variant of the enum. Each variant must have it’s own #[response(...)] definition. Unit variant will behave same as unit struct by creating a response without content. Similarly named field variant and unnamed field variant behaves the same as it was named field struct and unnamed field struct.

#[response] attribute can be used at named structs, unnamed structs, unit structs and enum variants to alter response attributes of responses.

Doc comment on a struct or enum variant will be used as a description for the response. It can also be overridden with description = "..." attribute.

IntoResponses #[response(...)] attributes

• status = ... Must be provided. Is either a valid http status code integer. E.g. 200 or a string value representing a range such as "4XX" or "default" or a valid http::status::StatusCode. StatusCode can either be use path to the status code or status code constant directly.

• description = "..." Define description for the response as str. This can be used to override the default description resolved from doc comments if present.

• content_type = "..." Can be used to override the default behavior of auto resolving the content type from the body attribute. If defined the value should be valid content type such as application/json . By default the content type is text/plain for primitive Rust types, application/octet-stream for [u8] and application/json for struct and mixed enum types.

• headers(...) Slice of response headers that are returned back to a caller.

• example = ... Can be json!(...). json!(...) should be something that serde_json::json! can parse as a serde_json::Value.

• examples(...) Define multiple examples for single response. This attribute is mutually exclusive to the example attribute and if both are defined this will override the example.

  • name = ... This is first attribute and value must be literal string.
  • summary = ... Short description of example. Value must be literal string.
  • description = ... Long description of example. Attribute supports markdown for rich text representation. Value must be literal string.
  • value = ... Example value. It must be json!(...). json!(...) should be something that serde_json::json! can parse as a serde_json::Value.
  • external_value = ... Define URI to literal example value. This is mutually exclusive to the value attribute. Value must be literal string.

  Example of example definition.

   ("John" = (summary = "This is John", value = json!({"name": "John"})))

Examples

Use IntoResponses to define utoipa::path responses.

#[derive(utoipa::ToSchema)]
struct BadRequest {
    message: String,
}

#[derive(utoipa::IntoResponses)]
enum UserResponses {
    /// Success response
    #[response(status = 200)]
    Success { value: String },

    #[response(status = 404)]
    NotFound,

    #[response(status = 400)]
    BadRequest(BadRequest),
}

#[utoipa::path(
    get,
    path = "/api/user",
    responses(
        UserResponses
    )
)]
fn get_user() -> UserResponses {
   UserResponses::NotFound
}

Named struct response with inlined schema.

/// This is success response
#[derive(utoipa::IntoResponses)]
#[response(status = 200)]
struct SuccessResponse {
    value: String,
}

Unit struct response without content.

#[derive(utoipa::IntoResponses)]
#[response(status = NOT_FOUND)]
struct NotFound;

Unnamed struct response with inlined response schema.

#[derive(utoipa::IntoResponses)]
#[response(status = 201)]
struct CreatedResponse(#[to_schema] Foo);

Enum with multiple responses.

#[derive(utoipa::IntoResponses)]
enum UserResponses {
    /// Success response description.
    #[response(status = 200)]
    Success { value: String },

    #[response(status = 404)]
    NotFound,

    #[response(status = 400)]
    BadRequest(BadRequest),

    #[response(status = 500)]
    ServerError(#[ref_response] Response),

    #[response(status = 418)]
    TeaPot(#[to_response] Response),
}