What are the best practices for defining a schema for nested or wrapped third-party types?

[vnermolaev]

Hi @juhaku,

I often find myself needing to create a schema for a type from a third-party crate, which can't be annotated with #[derive(ToSchema)].

To handle this, I usually define a function to manually create the schema for such types. For example, in the snippet below, Owner is a third-party type, and the owner_schema() function explicitly defines its schema.

If Owner is used as a field type, like in Pet, I can easily annotate it with #[schema(schema_with = owner_schema)], and everything works as expected.

However, if Owner is nested inside another type, like in Pet2, or wrapped in an enum variant, this approach no longer seems to work.

Is this use case supported? If not, what’s the recommended best practice for handling such scenarios?

/// I cannot annotate this type, it comes from a 3rd party crate.
struct Owner {
    name: String,
}

// I create a custom function to generate schema for `Owner`.
fn owner_schema() -> Schema {
    ObjectBuilder::new()
        .property(
            "name",
            ObjectBuilder::new().schema_type(Type::String).build(),
        )
        .required("name")
        .build()
        .into()
}

#[derive(ToSchema)] // Works perfectly.
struct Pet {
    #[schema(schema_with = owner_schema)]
    owner: Owner
}

#[derive(ToSchema)] // Fails.
struct Pet2(#[schema(schema_with = owner_schema)] Owner);

#[derive(ToSchema)] // Fails
pub enum PetStatus {
    Owned(
        #[schema(schema_with = owner_schema)]
        Owner
    ),
    Stray,
}