schema creation fails when field has a module-qualified type (at least when using axum)

[johnperry-math]

Version

latest

Description

See subject. (Sorry if I'm using the wrong terminology for "module-qualified type".)

Expected behavior

Schemas should be created even for module-qualified types.

MWE

Add the following to the utoipa-axum example:

mod commentary {
    use utoipa::ToSchema;

    #[derive(ToSchema, serde::Serialize, serde::Deserialize, Clone)]
    pub(super) struct Commentary {
        yada_yada: String,
    }
}

then the following import to mod todo:

use super::commentary;

and then the following field to struct Todo:

        commentary: commentary::Commentary,

Everything compiles and runs happily, but schema creation has failed. If you open the first endpoint or the Todo schema you get a red box listing the following error:

Errors

Resolver error at paths./todo.get.responses.200.content.application/json.schema.items.properties.commentary.$ref
Could not resolve reference: Could not resolve pointer: /components/schemas/commentary.Commentary does not exist in document

A workaround is to use super::commentary::Commentary but this is suboptimal for large projects where, for instance, you may be importing different Coordinates from different crates.

[johnperry-math]

This looks similar to #164, but that's about responses and this is about schema.

[johnperry-math]

Er... the above workaround does not actually seem to work in this case; I'm not sure why, but I still get the red Errors box. In my actual project I have a similar workaround and that works fine.

[juhaku]

For this there is a need to use as = attribute to alternate the name of the type to be derived. See related issues about namespaced schemas #230 , #435. E.g. we could use the as to rename to the commentary type.

#[derive(ToSchema)]
#[as = commentary::Commentary]
struct Commentary {
  value: String,
}

// .. in another type and module we can use the module path now.
#[derive(ToSchema)]
struct Foo {
  comments: commentary::Commentary,
}

[johnperry-math]

Do you mean this?

#[derive(ToSchema, serde::Serialize, serde::Deserialize, Clone)]
    #[schema(as = commentary::Commentary)]
    pub(super) struct Commentary {
        yada_yada: String,
    }

That does seem to do the trick in the example. I'll check with the "real" project and report back.

[juhaku]

Do you mean this?

Yes

[johnperry-math]

The real-world usage prompted a hiccup, because some crates import the type, and others import only its crate. To illustrate, suppose I modify the Todo struct as follows:

    #[derive(Serialize, Deserialize, ToSchema, Clone)]
    pub(super) struct Todo {
        id: i32,
        #[schema(example = "Buy groceries")]
        value: String,
        commentary: commentary::Commentary,
        more: Commentary, // HERE
        // ...
    }

Now it's the un-qualified Commentary that generates an error. However! this is easily solved using the value_type option:

    #[derive(Serialize, Deserialize, ToSchema, Clone)]
    pub(super) struct Todo {
        id: i32,
        #[schema(example = "Buy groceries")]
        value: String,
        commentary: commentary::Commentary,
        #[schema(value_type = commentary::Commentary)]
        more: Commentary, // HERE
        // ...
    }

...and I can work with this. Thank you!