Schemars serialization contract

[dnlsndr]

fixes #250

Note that this PR also contains fixes that were overlooked by me when I created the "upgrade to schemars 0.9.x" PR, namely crate features that I forgot to migrate.

[shovelmn12]

Please upgrade to 1.1.0

https://crates.io/crates/schemars

[dnlsndr]

@shovelmn12 that's outside of the scope of this PR.

[jplatte]

Also: #173 (comment)

[jplatte]

So, how is this going to behave when the same type is used both as an input and output? Will the result be dependent on the order in which the routes get registered / the inputs and outputs get processed by aide?

[dnlsndr]

Oversaw your message, double-checked it now, and you're correct that there's an issue with how the code would handle schema name collisions between the output and input generator.

At the moment, it's just doing a plain extend of the component schemas map, which would overwrite any schema definition that already exists in the map beforehand. Since it extends the input_generator with the definitions of the output_generator, any type that's used as an input and output would now get the schema of the output variant. So this is quite problematic.

I've looked into solving this by checking for collisions and then just renaming that colliding schema name to something like "Output_TestType" or "TestType2" or similar, but the issue is that schemars does not provide the necessary API to easily rename schema names within the whole schema. schemars also directly uses the schema_name() function for the JsonSchema trait impl of the type, so there's also no way that aide could intercept that to modify the type name on insertion. schemars has the concept of a Transform, but that doesn't allow us to modify the schema name, just the contents of the schema.

Ideally, we'd rely on the already in-built schema name collision handling of schemars, but to be able to do that we'd have to hold all schemas in the same SchemaGenerator. Doing that would prevent us from individually using different schema contracts though, which would render this whole endeavor obsolete.

Concluding: There's really no way of easily handling colliding types from the input and output schema. The only solution to this problem right now is to check for collisions and panic or return an error. We'll have to force the user to use the newtype pattern or just plainly define a second type with a different name that they can then use as an output or input type. Inlined schemas are not affected by this, so any primitive type is unproblematic. It's really just stuff that is added to the components of the OpenAPI spec, as they'll collide.

Another, probably rather dumb solution, would be to just inline everything. But that's a bad idea on many levels.