Derive Macro utoipa::ToResponse
source · #[derive(ToResponse)]
{
// Attributes available to this derive:
#[response]
#[content]
#[to_schema]
}
Expand description
Generate reusable OpenAPI response what can be used
in utoipa::path
or in OpenApi
.
This is #[derive]
implementation for ToResponse
trait.
#[response]
attribute can be used to alter and add response attributes.
#[content]
attributes is used to make enum variant a content of a specific type for the
response.
#[to_schema]
attribute is used to inline a schema for a response in unnamed structs or
enum variants with #[content]
attribute. Note! ToSchema
need to be implemented for
the field or variant type.
Type derived with ToResponse
uses provided doc comment as a description for the response. It
can alternatively be overridden with description = ...
attribute.
ToResponse
can be used in four different ways to generate OpenAPI response component.
-
By decorating
struct
orenum
withToResponse
derive macro. This will create a response with inlined schema resolved from the fields of thestruct
orvariants
of the enum.#[derive(ToResponse)] #[response(description = "Person response returns single Person entity")] struct Person { name: String, }
-
By decorating unnamed field
struct
withToResponse
derive macro. Unnamed field struct allows users to use new type pattern to define one inner field which is used as a schema for the generated response. This allows users to defineVec
andOption
response types. Additionally these types can also be used with#[to_schema]
attribute to inline the field’s type schema if it implementsToSchema
derive macro./// Person list response #[derive(utoipa::ToResponse)] struct PersonList(Vec<Person>);
-
By decorating unit struct with
ToResponse
derive macro. Unit structs will produce a response without body./// Success response which does not have body. #[derive(utoipa::ToResponse)] struct SuccessResponse;
-
By decorating
enum
with variants having#[content(...)]
attribute. This allows users to define multiple response content schemas to single response according to OpenAPI spec. Note! Enum withcontent
attribute in variants cannot have enum levelexample
orexamples
defined. Instead examples need to be defined per variant basis. Additionally these variants can also be used with#[to_schema]
attribute to inline the variant’s type schema if it implementsToSchema
derive macro.#[derive(utoipa::ToSchema)] struct Admin { name: String, } #[derive(utoipa::ToSchema)] struct Admin2 { name: String, id: i32, } #[derive(utoipa::ToResponse)] enum Person { #[response(examples( ("Person1" = (value = json!({"name": "name1"}))), ("Person2" = (value = json!({"name": "name2"}))) ))] Admin(#[content("application/vnd-custom-v1+json")] Admin), #[response(example = json!({"name": "name3", "id": 1}))] Admin2(#[content("application/vnd-custom-v2+json")] #[to_schema] Admin2), }
§ToResponse #[response(...)]
attributes
-
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 thebody
attribute. If defined the value should be valid content type such asapplication/json
. By default the content type istext/plain
for primitive Rust types,application/octet-stream
for[u8]
andapplication/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 bothjson
andxml
formats. The order of the content types define the default example show first in the Swagger UI. Swagger UI wil use the firstcontent_type
value as a default example. -
headers(...)
Slice of response headers that are returned back to a caller. -
example = ...
Can bejson!(...)
.json!(...)
should be something thatserde_json::json!
can parse as aserde_json::Value
. -
examples(...)
Define multiple examples for single response. This attribute is mutually exclusive to theexample
attribute and if both are defined this will override theexample
.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 bejson!(...)
.json!(...)
should be something thatserde_json::json!
can parse as aserde_json::Value
.external_value = ...
Define URI to literal example value. This is mutually exclusive to thevalue
attribute. Value must be literal string.
Example of example definition.
("John" = (summary = "This is John", value = json!({"name": "John"})))
§Examples
Use reusable response in operation handler.
#[derive(utoipa::ToResponse)]
struct PersonResponse {
value: String
}
#[derive(utoipa::OpenApi)]
#[openapi(components(responses(PersonResponse)))]
struct Doc;
#[utoipa::path(
get,
path = "/api/person",
responses(
(status = 200, response = PersonResponse)
)
)]
fn get_person() -> PersonResponse {
PersonResponse { value: "person".to_string() }
}
Create a response from named struct.
/// This is description
///
/// It will also be used in `ToSchema` if present
#[derive(utoipa::ToSchema, utoipa::ToResponse)]
#[response(
description = "Override description for response",
content_type = "text/xml"
)]
#[response(
example = json!({"name": "the name"}),
headers(
("csrf-token", description = "response csrf token"),
("random-id" = i32)
)
)]
struct Person {
name: String,
}
Create inlined person list response.
/// Person list response
#[derive(utoipa::ToResponse)]
struct PersonList(#[to_schema] Vec<Person>);
Create enum response from variants.
#[derive(utoipa::ToResponse)]
enum PersonType {
Value(String),
Foobar,
}