V0.2.0 preparation / Utoipa v5 support

[DenuxPlays]

The main goal is to get 100% compatible with utoipa v5.
closes: #44

TODOs

• add/complete the changelog
• add more acceptance tests
• fix tests
• remove generic schema discovery
• update documentation

Changelog

Breaking

• updated msrv to 1.75.0
• removed generic_full_path feature

Added

• generics acceptance tests
• responses acceptance tests

Changes

• added generic acceptance tests
• added responses acceptance tests
• updated test to utoipa v5

Removed

• removed Generic Schema support (as this is handled by utoipa now)

[DenuxPlays]

Test fail because the ToSchema derive is broken for constant generics:
juhaku/utoipa#1115

[DenuxPlays]

Still some weird things that needs investigating:

Without the new schema_discovery feature there are routes missing?
Still no schemas are auto-discovered by utoipa (I guess this has something to do with the other issue mentioned above)

[DenuxPlays]

As long as responses (including their schemas) are not being auto-discovered we cannot remove schema discovery/put it behind a feature flag.
Related issue: juhaku/utoipa#1094

This will not stop or impact the development just a note.

[DenuxPlays]

@ProbablyClem I think this is ready.

Can you please take a look at it.

[ProbablyClem]

Great PR thanks :

[DenuxPlays]

Thank you :)

I would merge this pr.
Can you create a new release then?

[domenicquirl]

@DenuxPlays is it intentional that this means that structs that derive ToResponse but have a lifetime will no longer be detected? We have some code that looks like

#[derive(Debug, Clone, Serialize, ToSchema, ToResponse)]
pub(crate) struct TopicInfo<'a> {
    #[schema(schema_with = kind_schema)]
    topics: HashMap<&'a str, Kind>,
}

which we use to avoid allocating Strings for these topics that are going to be serialized anyways as part of the response. In [email protected], this was discovered by utoipauto and added to the #[openapi] directive - we just had responses( (status = StatusCode::OK, response = TopicInfo) ) on the #[utoipa::path]. In 0.2, TopicInfo disappears from the schema.

If I put (status = StatusCode::OK, description = "A list of known topics.", body = TopicInfo) as the responses instead, it shows up (only in the schemas part) - unsure if that's utoipauto or the new schema discovery in utoipa@5. But I have also confirmed that if I use the old condition for the early return instead, TopicInfo is included in the responses as well.

Would there be any issues with only using the new, more strict check for schemas but keep the old check for responses?

[DenuxPlays]

I dont really remember this code tbh.

But I think lifetimes aren't supported by utoipa in v5?
If they are then they should be auto discovered.

If there is a bug in the auto-discovery feature feel free to open a pr to fix it or an issue to document it.

[DenuxPlays]

But I think the code is faulty.

We should check for explicit generic parameters excluding lifetimes.
But I remember that something like this has already be done or came up?
Idk really remember tbh.

[domenicquirl]

What exactly do you mean by "not supported"? Both ToSchema and ToResponse work fine with, for example, MyType<'a> containing a &'a str (which is correctly represented as schema type "string"). So as long as the type is part of the OpenAPI declaration at all, this has been working fine even in v4. Or maybe I'm missing something?

utoipa very much claims support for generics in their README (as long as you use the derives). juhaku/utoipa#1034 also includes a type with a lifetime parameter in the examples, so I'd expect this to "just work" (except for maybe const generics) 🤔

[DenuxPlays]

Oh wait my memory is coming back.
We do this because schemas are getting autodiscovered.
Our Problem is that we cannot predict which type of generic you use.
I think that Utoipa converts this SomeType<String> to SomeTypeString.
So basically what the aliases macro did in v4.
In v4 we parsed the aliases macro and added all the types but this isn't possible in v5.

So the real issue is this:
juhaku/utoipa#1094

I am not sure if we can develop a work-around for now.
Atleast I don't have the time to.

[domenicquirl]

Hm, why do we need to predict anything here? Can't we (syn) look at what kind of generic the macro is parsing?

What you're saying about the name change seems right (except that I think it becomes SomeType_String), but I can't see how this is particularly related to lifetimes, which should just be ignored by the name conversion?

FWIW, I also opened #50 which just reverts the discovery check. It doesn't do anything about previously having handling for aliases, honestly I haven't ever used it so I'm not sure what we would need to be doing there either.