[Generator] Multiple content types support

[czechboy0]

Depends on apple/swift-openapi-runtime#29

Motivation

Up until now, when an OpenAPI document contained more than one content type in either a request or a response body, we would only generate code for now, and ignored the other ones.

However, that was a temporary workaround until we could add proper support for multiple content types, which is what this PR is about.

Addresses #6 and #7, except for the "Accept header" propagation, which will be addressed separately and have its own PR and even a proposal. That's one of the reasons this feature is landing disabled, hidden behind the multipleContentTypes feature flag.

A tip for reviewing this change: first check out how the test OpenAPI document and the reference files changed, that shows the details of how we encode and decode multiple content types. I also added comments in the code for easier review.

Modifications

• Main: all supported content types found in a content map in request and response bodies are now generated in the Body enum.
• Added a method supportedTypedContents that returns all supported content types, used now instead of the bestTypedContent method we used before. What is a "supported" content type? One that has a schema that doesn't return false to isSchemaSupported. (This is a pre-existing concept.)
• Updated the logic for generating request and response bodies to use the new method, both on client and server.
• Updated content type -> Swift enum case name logic, but that will go through a full proposal, so please hold feedback for the proposal, this is just a first pass based on some collected data of most commonly used content types.

Open Questions

• What to do in an operation with multiple request/response content types when no content-type header is provided? Previously, with up to 1 content type support, we still went ahead and tried to parse it. But here, we don't know which content to parse it as, so we just try it with the first in the list (we respect the order in the YAML dictionary, so what the user put first will be what we try to use when no content-type header is provided). If an invalid content-type value is provided, we throw an error (pre-existing behavior). Q: Is choosing the first reasonable? What would be better? Note that, unfortunately, many servers don't send content-type today.

Result

When an adopter provides multiple content types in their OpenAPI document, we generate one case in the Body enum for each! However, the new functionality is disabled by default, has to be explicitly requested by enabling the multipleContentTypes feature flag either on the CLI or in the config file.

Test Plan

Added setStats and getStats operations that employ multiple content types, one in a request body, the other in a response body. Added unit tests for it in PetstoreConsumerTests to verify it all works correctly at runtime.

Deleted Tests/OpenAPIGeneratorCoreTests/Translator/RequestBody/Test_translateRequestBody.swift as snippet tests do this job better, and I didn't want to spend the time updating the test.

Adds PetstoreConsumerTests_FF_MultipleContentTypes, a variant of PetstoreConsumerTests for when the multipleContentTypes feature flag is enabled, so we test both how the existing logic handles multiple content types (it picks one), and the new logic (it generates code for all supported ones it found).

TODOs

• rename IfConditionPair to IfBranch
• break out the first if from the subsequence else ifs in IfStatement, to 3 properties: first if, then an array of else ifs, then an optional else; to avoid creating invalid code
• create an SPI type ContentType to avoid repeatedly parsing the received content type

[simonjbeaumont]

Before digging into the review proper, thought I'd pick up on this question:

What to do in an operation with multiple request/response content types when no content-type header is provided? Previously, with up to 1 content type support, we still went ahead and tried to parse it. But here, we don't know which content to parse it as, so we just try it with the first in the list (we respect the order in the YAML dictionary, so what the user put first will be what we try to use when no content-type header is provided). If an invalid content-type value is provided, we throw an error (pre-existing behavior). Q: Is choosing the first reasonable? What would be better? Note that, unfortunately, many servers don't send content-type today.

I think it's reasonable for us to throw an error if Content-Type is provided but doesn't match what we get. However, in the case the server omits Content-Type, shouldn't we be trying all of them, not just the first, similar to how we handle anyOf/oneOf? Failing if it doesn't match the first seems to be overly restrictive since it will reject a response from the server which is "in spec"? Or have I misunderstood?

[czechboy0]

Trying all of them is another option, yeah. Although if the first content type is a binary type, we'll never fail to parse as it, and move to the next one. But if it's ordered from the most to least restrictive, this would work well. One concern about this would be performance, as trying to parse large (e.g. image) data as JSON might be slow, but if it still "works", the adopter might not know they should probably go and fix their server or OpenAPI doc.

So, to recap our options:

• try all, until one that works
• try the first one only
• throw an error if no content type is provided, and more than 1 content type is documented

[simonjbeaumont]

Thanks for taking the time to rebase this PR for easier review. It's looking really good. I've added a few questions, otherwise I think it's looking really good!

[gjcairo]

Q: Is choosing the first reasonable? What would be better?

Answering this question from the description: I think this is reasonable. The only alternative is to send supported ones, I guess, but I'm not sure what benefit this would have over sending just the first one.