[REQ] Support Multiple Response Schemas For A Single Endpoint

Created by: BenjaminHetzjelli

Is your feature request related to a problem? Please describe.

Our general use case is generating a Java client for our APIs for use in integration tests.

Our issue is a single endpoint, which can conditionally return its data as either plaintext CSV or as our own type in JSON based upon an input parameter. Below is the yaml for describing the responses for this endpoint.

responses:
  "404":
    description: <desc>
  "403":
    description: <desc>
  "401":
    description: <desc>
  "202":
    description: <desc>
  "200":
    description: <desc>
      content:
        text/plain:
          schema:
            type: string
        application/json;charset=utf-8:
          schema:
            type: array
              items:
                $ref: '#/components/schemas/<OurType>'

The behavior that appears is that the generated java method can only return one type (obviously). The type of the generated method changes depending upon which content type is declared first, so the snippet above gives a method that returns String, but reversing the declarations in content results in a method that returns OurType.

Describe the solution you'd like

If possible, allowing the generator to create multiple methods (1 for each response type maybe) for each path could be a solution.

Describe alternatives you've considered

We have considered modifying our Swagger annotations such that the method always returns string, and then do our own deserialisation in our usage of the generated clients.

Additional context

The documentation for OpenAPI 3.0 appears to indicate that defining multiple content types is valid, if not explicitly then by the examples making use of it. https://swagger.io/docs/specification/describing-responses/