pub trait ToSchema: PartialSchema {
// Provided methods
fn name() -> Cow<'static, str> { ... }
fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>) { ... }
}Expand description
Trait for implementing OpenAPI Schema object.
Generated schemas can be referenced or reused in path operations.
This trait is derivable and can be used with [#derive] attribute. For a details of
#[derive(ToSchema)] refer to derive documentation.
§Examples
Use #[derive] to implement ToSchema trait.
#[derive(ToSchema)]
#[schema(example = json!({"name": "bob the cat", "id": 1}))]
struct Pet {
id: u64,
name: String,
age: Option<i32>,
}Following manual implementation is equal to above derive one.
impl utoipa::ToSchema for Pet {
fn name() -> std::borrow::Cow<'static, str> {
std::borrow::Cow::Borrowed("Pet")
}
}
impl utoipa::PartialSchema for Pet {
fn schema() -> utoipa::openapi::RefOr<utoipa::openapi::schema::Schema> {
utoipa::openapi::ObjectBuilder::new()
.property(
"id",
utoipa::openapi::ObjectBuilder::new()
.schema_type(utoipa::openapi::schema::Type::Integer)
.format(Some(utoipa::openapi::SchemaFormat::KnownFormat(
utoipa::openapi::KnownFormat::Int64,
))),
)
.required("id")
.property(
"name",
utoipa::openapi::ObjectBuilder::new()
.schema_type(utoipa::openapi::schema::Type::String),
)
.required("name")
.property(
"age",
utoipa::openapi::ObjectBuilder::new()
.schema_type(utoipa::openapi::schema::Type::Integer)
.format(Some(utoipa::openapi::SchemaFormat::KnownFormat(
utoipa::openapi::KnownFormat::Int32,
))),
)
.example(Some(serde_json::json!({
"name":"bob the cat","id":1
})))
.into()
}
}Provided Methods§
Sourcefn name() -> Cow<'static, str>
fn name() -> Cow<'static, str>
Return name of the schema.
Name is used by referencing objects to point to this schema object returned with
PartialSchema::schema within the OpenAPI document.
In case a generic schema the name will be used as prefix for the name in the OpenAPI
documentation.
The default implementation naively takes the TypeName by removing
the module path and generic elements.
But you probably don’t want to use the default implementation for generic elements.
That will produce collision between generics. (eq. Foo<String> )
§Example
struct Foo<T>(T);
impl<T: ToSchema> ToSchema for Foo<T> {}
assert_eq!(Foo::<()>::name(), std::borrow::Cow::Borrowed("Foo"));
assert_eq!(Foo::<()>::name(), Foo::<i32>::name()); // WARNING: these types have the same nameSourcefn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)
fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)
Implement reference utoipa::openapi::schema::Schemas for this type.
When ToSchema is being derived this is implemented automatically but if one needs to
manually implement ToSchema trait then this is needed for utoipa to know
referencing schemas that need to be present in the resulting OpenAPI spec.
The implementation should push to schemas Vec all such field and variant types that
implement ToSchema and then call <MyType as ToSchema>::schemas(schemas) on that type
to forward the recursive reference collection call on that type.
§Examples
Implement ToSchema manually with references.
#[derive(ToSchema)]
struct Owner {
name: String
}
struct Pet {
owner: Owner,
name: String
}
impl PartialSchema for Pet {
fn schema() -> utoipa::openapi::RefOr<utoipa::openapi::schema::Schema> {
utoipa::openapi::schema::Object::builder()
.property("owner", Owner::schema())
.property("name", String::schema())
.into()
}
}
impl ToSchema for Pet {
fn schemas(schemas:
&mut Vec<(String, utoipa::openapi::RefOr<utoipa::openapi::schema::Schema>)>) {
schemas.push((Owner::name().into(), Owner::schema()));
<Owner as ToSchema>::schemas(schemas);
}
}Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.