Migrate header, path param, query param serialization to URI coder, deprecate _StringConvertible

[czechboy0]

Today, one can only use _StringConvertible types in places like query parameters, headers, and so on.

This works well for native primitive types, like String, Int, Double, and Bool; and we also made it work for string-based generated enums (which are essentially strings with an extra constraint).

However, when used with, for example, a oneOf that is either a string or an int, this doesn't work, as we generate an enum with associated values, and even though all the underlying cases are themselves _StringConvertible, the oneOf itself isn't. That prevents adopters from doing things that are legal in OpenAPI, and can be pretty useful (an example is the Weather.gov OpenAPI doc described in #135).

A solution to this could look as follows:

• if all subschemas of a oneOf/allOf/anyOf are _StringConvertible (we have util functions in the generator already to check this), add the RawRepresentable and _AutoLosslessStringConvertible conformances on the type itself as well
• this will require generating a custom init(rawValue:) initializer and a rawValue property getter, but we also already did that for string-based enums, so we can take inspiration there
• note: in the rawValue property getter, we should dynamically check the undocumented contents of the OpenAPIRuntime.OpenAPIValueContainer, and if it's itself convertible to string, return it, but otherwise throw an error – this is for cases when e.g. an object was provided, we don't want to stringify it

Once this is in place, compositions of _StringConvertible types will also be _StringConvertible, and will be usable in those contexts, especially in query and header parameters.

[czechboy0]

First wave of this should cover just oneOf, and only if it doesn't have a discriminator (as if it does, then it can't be string-convertible, as it's an object, not a primitive value). We'll need to see real-world examples of this being necessary for allOf/anyOf or other types.

[czechboy0]

I've been playing with this a bit on a branch, the fact that we have the undocumented cases on all string enum schemas actually makes things a little more difficult, as for nested string schemas, we don't want them to successfully parse. I've been experimenting with separating the parsing into a init?(onlyDocumented:) (which returns nil for undocumented) and init(rawValue:) which calls the former and then assigns .undocumented if the former returned nil. Then we can call the appropriate initializer, based on whether we want to get an undocumented or not. That's the missing building block, the rest should be a bit easier.

[czechboy0]

Pausing on this for a moment, as I'm overall unhappy with the existence of the _StringConvertible protocol and would like to explore if we could rely purely on Codable + one or two new custom encoders and decoders. More info: #182 (comment)

[czechboy0]

Marking this blocked for now, as this would be a pretty large amount of work but wouldn't scale to eventually make it possible to support all the generated types, not just the hand-picked ones.

[czechboy0]

Renaming accordingly, we'll go forward with the new coders and deprecate _StringConvertible completely.