Trait ToSchema

pub trait ToSchema<'__s> {
    // Required method
    fn schema() -> (&'__s str, RefOr<Schema>);

    // Provided method
    fn aliases() -> Vec<(&'__s str, 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<'__s> utoipa::ToSchema<'__s> for Pet {
    fn schema() -> (&'__s str, utoipa::openapi::RefOr<utoipa::openapi::schema::Schema>) {
         (
            "Pet",
            utoipa::openapi::ObjectBuilder::new()
                .property(
                    "id",
                    utoipa::openapi::ObjectBuilder::new()
                        .schema_type(utoipa::openapi::SchemaType::Integer)
                        .format(Some(utoipa::openapi::SchemaFormat::KnownFormat(
                            utoipa::openapi::KnownFormat::Int64,
                        ))),
                )
                .required("id")
                .property(
                    "name",
                    utoipa::openapi::ObjectBuilder::new()
                        .schema_type(utoipa::openapi::SchemaType::String),
                )
                .required("name")
                .property(
                    "age",
                    utoipa::openapi::ObjectBuilder::new()
                        .schema_type(utoipa::openapi::SchemaType::Integer)
                        .format(Some(utoipa::openapi::SchemaFormat::KnownFormat(
                            utoipa::openapi::KnownFormat::Int32,
                        ))),
                )
                .example(Some(serde_json::json!({
                  "name":"bob the cat","id":1
                })))
                .into(),
        ) }
}

Required Methods

fn schema() -> (&'__s str, RefOr<Schema>)

Return a tuple of name and schema or reference to a schema that can be referenced by the name or inlined directly to responses, request bodies or parameters.

Provided Methods

fn aliases() -> Vec<(&'__s str, Schema)>

Optional set of alias schemas for the ToSchema::schema.

Typically there is no need to manually implement this method but it is instead implemented by derive ToSchema when #[aliases(...)] attribute is defined.

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.

Implementors

impl<'__s> ToSchema<'__s> for TupleUnit