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 = "..." | 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 complex enum types. Content type can also be slice of content_type values if the endpoint support returning multiple response content types. E.g ["application/json", "text/xml"] would indicate that endpoint can return both json and xml formats. The order of the content types define the default example show first in the Swagger UI. Swagger UI wil use the first content_type value as a default example.

• 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),
}