Trait ToSchema

pub trait ToSchema: PartialSchema {
    // Provided methods
    fn name() -> Cow<'static, str> { ... }
    fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>) { ... }
}

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

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

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implement reference fastapi::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 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 &str

fn name() -> Cow<'static, str>

impl ToSchema for Value

impl ToSchema for bool

fn name() -> Cow<'static, str>

impl ToSchema for char

fn name() -> Cow<'static, str>

impl ToSchema for f32

fn name() -> Cow<'static, str>

impl ToSchema for f64

fn name() -> Cow<'static, str>

impl ToSchema for i8

fn name() -> Cow<'static, str>

impl ToSchema for i16

fn name() -> Cow<'static, str>

impl ToSchema for i32

fn name() -> Cow<'static, str>

impl ToSchema for i64

fn name() -> Cow<'static, str>

impl ToSchema for i128

fn name() -> Cow<'static, str>

impl ToSchema for isize

fn name() -> Cow<'static, str>

impl ToSchema for str

fn name() -> Cow<'static, str>

impl ToSchema for u8

fn name() -> Cow<'static, str>

impl ToSchema for u16

fn name() -> Cow<'static, str>

impl ToSchema for u32

fn name() -> Cow<'static, str>

impl ToSchema for u64

fn name() -> Cow<'static, str>

impl ToSchema for u128

fn name() -> Cow<'static, str>

impl ToSchema for usize

fn name() -> Cow<'static, str>

impl ToSchema for String

fn name() -> Cow<'static, str>

impl<'a, T: ToSchema + Clone> ToSchema for Cow<'a, T>

where Cow<'a, T>: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<'t, T: ToSchema> ToSchema for &'t [T]

where &'t [T]: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<'t, T: ToSchema> ToSchema for &'t mut [T]

where &'t mut [T]: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<K: ToSchema> ToSchema for BTreeSet<K>

where BTreeSet<K>: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<K: ToSchema> ToSchema for HashSet<K>

where HashSet<K>: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<K: ToSchema, T: ToSchema> ToSchema for BTreeMap<K, T>

where BTreeMap<K, T>: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<K: ToSchema, T: ToSchema> ToSchema for HashMap<K, T>

where HashMap<K, T>: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<T: ToSchema> ToSchema for Option<T>

where Option<T>: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<T: ToSchema> ToSchema for [T]

where [T]: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<T: ToSchema> ToSchema for Box<T>

where Box<T>: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<T: ToSchema> ToSchema for LinkedList<T>

where LinkedList<T>: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<T: ToSchema> ToSchema for Vec<T>

where Vec<T>: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

impl<T: ToSchema> ToSchema for RefCell<T>

where RefCell<T>: PartialSchema,

Available on crate feature macros only.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implementors

impl ToSchema for TupleUnit