Improve ergonomics when switching over Outputs

[clarkkent-superman]

Getting down to the actual response model object requires drilling down through few layers of structs and enums:

switch result {
case let .ok(reponse):
    case let .json(payload):
        print(payload.body, payload.headers)
    @unknown default:
        break
    }
@unknown default:
    break
} 

I understand there is a requirement to handle multiple response types. If the payload could be flattened into just a body and headers, instead of a struct containing both of these, it would be possible to use the following syntax which would still support multiple response types.

switch result {
case let .ok(.json(body, headers):
  print(body, headers)
@unknown default:
    break
} 

[simonjbeaumont]

@clarkkent-superman thanks for filing this issue.

As you noted, the API of the generated code is designed to be as expressive as the OpenAPI specification allows. This includes multiple response bodies.

The spec for the response object specifies a response have headers and then a content map for various media types—i.e. the headers are shared across all possible content types for that response.

You're correct: it does result in a verbose API for simple operations that have a single content type. However, our goal was to generate code that would evolve in a sensible way as the API evolves.

For example, when an operation that has a single content type grows the ability to provide an additional body content type. The experience today is that clients will have another enum case to handle, which feels like an idiomatic mapping to Swift.

While we want to retain the expressive API layer, we are definitely interested in adding some conveniences/sugar APIs on top if/when they make sense, and we'd definitely welcome a contribution in this area. However, we'd need to have a well-thought-out design first. Issue #22 has some ideas, which might overlap with this issue.

Could you elaborate on the flattening you have in mind? Would we then need to duplicate the headers object into each of the response body type enum cases?

//cc @czechboy0

[czechboy0]

Just to add to @simonjbeaumont - I think the generated base layer will continue to map the structure of OpenAPI (i.e., we likely won't duplicate the headers in every response enum case just to make the switching easier).

However, we're very open to adding sugar on top of the generated base layer. We'd like to see examples of what folks think it should look like, and we can take it from there.

Seeing specific ideas also helps us decide whether it should be part of the generated code, or if it should be a separate, e.g. macro package, that folks can explicitly opt-into to get the extra sugar, without growing the generated base layer.

A lot of questions, so we need to see some ideas 🙂

[czechboy0]

Tagged as needing design – but feel free to add ideas in this issue until someone puts together a concrete proposal.

[PadraigK]

❤️ Nice!