Allow multiple protocols for OpenAPI conversions

[humanzz]

This is a Feature Request to allow the openapi conversion plugin - https://smithy.io/2.0/guides/model-translations/converting-to-openapi.html - to support multiple protocols if the the service as defined in Smithy model support multiple protocols.

Context
I have a Smithy model, defining a service, and it's used for both server/client codegen. The service's runtime is a Lambda Function with an API Gateway infront of it. The API Gateway is setup using using CDK's SpecRestApi by leveraging the OpenAPI conversion plugin.

The model defines the service to use the aws.protocols#restJson1, and I'm looking into getting it to support smithy.protocols#rpcv2Cbor

The Request

In smithy-build.json, one can define multiple openapi conversions e.g. openapi::restjson and openapi::rpcv2 to end up with 2 different openapi conversions e.g.

...
"openapi::restjson": {
  ...
  "protocol": "aws.protocols#restJson1"
},
"openapi::rpcv2": {
  ...
  "protocol": "amazon.protocols#smithyRpcV2"
}
...

and when I look at the diff between the conversions, the only difference in is in the paths section, and to me, it looks like at least with those 2 protocols, the same API Gateway, as defined by a single openapi definition, can support both.

As such, this is a request, to allow for multiple protocols into the same openapi conversion (which can maybe be achieved by merging 2 conversions, so long as they don't overwrite each other)

[mtdowling]

Generating an OpenAPI description that contains the HTTP messages for multiple Smithy protocols would need some design work. Because Smithy is focused on the usage of a service rather than focusing on HTTP bits on the wire, the input of an operation contains all the fields a user might want to pass to a service, in a single place. However, in OpenAPI, details like HTTP headers and query string parameters are captured separately from the payload of a request. To account for this when converting Smithy to OpenAPI, protocols that use HTTP bindings have to create synthetic shapes in OpenAPI to capture things like headers and query strings separate from the payload of a request/response. RPC protocols wouldn't use that same transformation. So we'd need to think through how we'd deal with the differences between the synthetic input/output shapes vs the actual input/output shapes.

[humanzz]

Given I have a simple API that does not leverage HTTP headers are query params, when I diff-ed the generated openapi from my run above, there was no difference except in paths. So, I do get the point that supporting the entirety of Smithy features, and converting that to OpenAPI for multiple protocols is not as simple as I first thought.

Appreciate the response, and I look forwards to what you folks come up with, as I think more folks will be running into similar questions, as existing services try to rollout newer more efficient protocols like rpvV2Cbor to their existing users.