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 fastapi::ToSchema for Pet {
fn name() -> std::borrow::Cow<'static, str> {
std::borrow::Cow::Borrowed("Pet")
}
}
impl fastapi::PartialSchema for Pet {
fn schema() -> fastapi::openapi::RefOr<fastapi::openapi::schema::Schema> {
fastapi::openapi::ObjectBuilder::new()
.property(
"id",
fastapi::openapi::ObjectBuilder::new()
.schema_type(fastapi::openapi::schema::Type::Integer)
.format(Some(fastapi::openapi::SchemaFormat::KnownFormat(
fastapi::openapi::KnownFormat::Int64,
))),
)
.required("id")
.property(
"name",
fastapi::openapi::ObjectBuilder::new()
.schema_type(fastapi::openapi::schema::Type::String),
)
.required("name")
.property(
"age",
fastapi::openapi::ObjectBuilder::new()
.schema_type(fastapi::openapi::schema::Type::Integer)
.format(Some(fastapi::openapi::SchemaFormat::KnownFormat(
fastapi::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 name
Sourcefn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)
fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)
Implement reference fastapi::openapi::schema::Schema
s 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 fastapi
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() -> fastapi::openapi::RefOr<fastapi::openapi::schema::Schema> {
fastapi::openapi::schema::Object::builder()
.property("owner", Owner::schema())
.property("name", String::schema())
.into()
}
}
impl ToSchema for Pet {
fn schemas(schemas:
&mut Vec<(String, fastapi::openapi::RefOr<fastapi::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.
Implementations on Foreign Types§
impl ToSchema for Value
Source§impl<'a, T: ToSchema + Clone> ToSchema for Cow<'a, T>where
Cow<'a, T>: PartialSchema,
Available on crate feature macros
only.
impl<'a, T: ToSchema + Clone> ToSchema for Cow<'a, T>where
Cow<'a, T>: PartialSchema,
macros
only.Source§impl<'t, T: ToSchema> ToSchema for &'t [T]where
&'t [T]: PartialSchema,
Available on crate feature macros
only.
impl<'t, T: ToSchema> ToSchema for &'t [T]where
&'t [T]: PartialSchema,
macros
only.Source§impl<'t, T: ToSchema> ToSchema for &'t mut [T]where
&'t mut [T]: PartialSchema,
Available on crate feature macros
only.
impl<'t, T: ToSchema> ToSchema for &'t mut [T]where
&'t mut [T]: PartialSchema,
macros
only.Source§impl<K: ToSchema> ToSchema for BTreeSet<K>where
BTreeSet<K>: PartialSchema,
Available on crate feature macros
only.
impl<K: ToSchema> ToSchema for BTreeSet<K>where
BTreeSet<K>: PartialSchema,
macros
only.Source§impl<K: ToSchema> ToSchema for HashSet<K>where
HashSet<K>: PartialSchema,
Available on crate feature macros
only.
impl<K: ToSchema> ToSchema for HashSet<K>where
HashSet<K>: PartialSchema,
macros
only.Source§impl<K: ToSchema, T: ToSchema> ToSchema for BTreeMap<K, T>where
BTreeMap<K, T>: PartialSchema,
Available on crate feature macros
only.
impl<K: ToSchema, T: ToSchema> ToSchema for BTreeMap<K, T>where
BTreeMap<K, T>: PartialSchema,
macros
only.Source§impl<K: ToSchema, T: ToSchema> ToSchema for HashMap<K, T>where
HashMap<K, T>: PartialSchema,
Available on crate feature macros
only.
impl<K: ToSchema, T: ToSchema> ToSchema for HashMap<K, T>where
HashMap<K, T>: PartialSchema,
macros
only.Source§impl<T: ToSchema> ToSchema for Option<T>where
Option<T>: PartialSchema,
Available on crate feature macros
only.
impl<T: ToSchema> ToSchema for Option<T>where
Option<T>: PartialSchema,
macros
only.Source§impl<T: ToSchema> ToSchema for [T]where
[T]: PartialSchema,
Available on crate feature macros
only.
impl<T: ToSchema> ToSchema for [T]where
[T]: PartialSchema,
macros
only.Source§impl<T: ToSchema> ToSchema for Box<T>where
Box<T>: PartialSchema,
Available on crate feature macros
only.
impl<T: ToSchema> ToSchema for Box<T>where
Box<T>: PartialSchema,
macros
only.Source§impl<T: ToSchema> ToSchema for LinkedList<T>where
LinkedList<T>: PartialSchema,
Available on crate feature macros
only.
impl<T: ToSchema> ToSchema for LinkedList<T>where
LinkedList<T>: PartialSchema,
macros
only.Source§impl<T: ToSchema> ToSchema for Vec<T>where
Vec<T>: PartialSchema,
Available on crate feature macros
only.
impl<T: ToSchema> ToSchema for Vec<T>where
Vec<T>: PartialSchema,
macros
only.Source§impl<T: ToSchema> ToSchema for RefCell<T>where
RefCell<T>: PartialSchema,
Available on crate feature macros
only.
impl<T: ToSchema> ToSchema for RefCell<T>where
RefCell<T>: PartialSchema,
macros
only.