Improving support for FooId(pub uuid::Uuid)

[jayvdb]

We recently moved from having lots of use of format: uuid throughout our schemas to having dedicated struct for each "id", where each one was like

#[derive(Clone, Copy, Debug, Default, Deserialize, Dummy, Eq, Hash, PartialEq, Serialize, actix_default_responder::JsonResponder, utoipa::ToSchema)]
pub struct FooId(pub uuid::Uuid);
impl ...

This has the benefit that now all of our foo_id fields are strictly only able to contain a FooId and cant accidentally contain a BarId.

The main issue we had was that this meant we needed to be explicit when declaring the params
i.e. they now look like

#[utoipa::path(
    params(
        ("foo_id" = FooId, description = "Foo identifier"),
    ),
    responses(
        (status = 200, description = "Foo data sent", body = Foo)
    ),
)]
#[get("/foo/{foo_id}")]
pub async fn fetch_foo(app_data: Data<AppData>, foo_id: Path<FooId>) -> Result<impl Responder> {
    ...
}

When we were directly using uuid::Uuid, such as pub async fn fetch_foo(app_data: Data<AppData>, foo_id: Path<FooId>) ... we did not need to do the = FooId

i.e. there is some special support for uuid::Uuid so it was implicit, but when we wrapped the uuid, we needed to do this change everywhere

-        ("foo_id", description = "Foo identifier"),
+        ("foo_id" = FooId, description = "Foo identifier"),

This is not a 'problem', but if it is easy to avoid, it would be worth attempting. What section of the code should I start looking to improve utoipa's support for this wrapped Uuid.

[juhaku]

I belive this comes from framework specific extensions. E.g. it did automatically update the parameter types based on function arguments. But it only supports naively "known" types e.g. primitive and Uuid etc.

utoipa-gen/src/lib.rs:1340 might be a good place to start looking. And then to dive into the functions related to the path and path parameters. It is in the utoipa-gen/src/path.rs where the parameters are being added to the path and utoipa-gen/src/ext/actix.rs and utoipa-gen/src/ext.rs where the parameters are being resolved.

[JMLX42]

When using #[serde(flatten)] + #[schema(default = ...) (or example = ...) on the newtype:

1. allOf is used to support #[serde(flatten)] (cf #[serde(flatten)] may not be supported (yet) #120 (comment))
2. The OpenAPI specification assumes all the items of allOf have their example (or default) field set

#[derive(serde::Deserialize, ToSchema, Default)]
struct Name {
    firstname: String,
    lastname: String,
}

#[derive(serde::Deserialize, ToSchema, Default)]
#[schema(default = json!({ "firstname": "Jean-Luc", "lastname": "Picard" }))]
struct OwnerName(
    Name,
);

#[derive(serde::Deserialize, ToSchema, Default)]
struct Owner {
    num_books: u64,
    #[schema(inline)]
    #[serde(flatten)]
    name: OwnerName,
}

(note how num_books is missing 👆 )

And AFAIK the only solution is to set default = ... (or example = ...) on all fields.

What's unsettling is that without inlining/flattening, there is no allOf so the Swagger UI assumes default/example values for all fields:

[JMLX42]

(note how num_books is missing point_up_2 )

And AFAIK the only solution is to set default = ... (or example = ...) on all fields.

What's unsettling is that without inlining/flattening, there is no allOf so the Swagger UI assumes default/example values for all fields:

It is most likely a Swagger UI bug. It renders fine in ReDoc:

[juhaku]

Yeah, I could update the Swagger UI to see if this get's solved. I also added a support for Redoc recently.