utoipa

Trait ToSchema

Source
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§

Source

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
Source

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.

Implementations on Foreign Types§

Source§

impl ToSchema for &str

Source§

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

Source§

impl ToSchema for Value

Source§

impl ToSchema for bool

Source§

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

Source§

impl ToSchema for char

Source§

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

Source§

impl ToSchema for f32

Source§

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

Source§

impl ToSchema for f64

Source§

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

Source§

impl ToSchema for i8

Source§

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

Source§

impl ToSchema for i16

Source§

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

Source§

impl ToSchema for i32

Source§

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

Source§

impl ToSchema for i64

Source§

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

Source§

impl ToSchema for i128

Source§

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

Source§

impl ToSchema for isize

Source§

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

Source§

impl ToSchema for str

Source§

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

Source§

impl ToSchema for u8

Source§

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

Source§

impl ToSchema for u16

Source§

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

Source§

impl ToSchema for u32

Source§

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

Source§

impl ToSchema for u64

Source§

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

Source§

impl ToSchema for u128

Source§

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

Source§

impl ToSchema for usize

Source§

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

Source§

impl ToSchema for String

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

impl<T: ToSchema> ToSchema for [T]

Source§

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

Source§

impl<T: ToSchema> ToSchema for Box<T>
where Box<T>: PartialSchema,

Source§

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

Source§

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

Source§

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

Source§

impl<T: ToSchema> ToSchema for Vec<T>
where Vec<T>: PartialSchema,

Source§

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

Source§

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

Source§

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

Implementors§