Improve OpenAPI support for enums as map keys

[denisrosca]

Improve enum support as map keys by utilizing the newly added propertyNames JSON Schema in OpenAPI 3.1.

Background

There's a mismatch in support of enums as map keys between Smithy and OpenAPI. Currently when converting a smithy definition containing a map shape with an enum as key, the generated Open API spec discards all enum information and treats the map shape a simple string to object mapping.

Given this simple Smithy service:

$version: "2"

namespace enumkeys.example

use aws.protocols#restJson1

@restJson1
service ExampleService {
  version: "1.0.0"
  operations: [MajorCitiesByCountry]
}

@http(method: "GET", uri: "/cities", code: 200)
@readonly
operation MajorCitiesByCountry {
  output : Response
}

enum Country {
  UK = "UK"
  FR = "FR"
  US = "US"
  DE = "DE"
}

string City

list Cities {
    member: City
}

map CitiesByCountry {
  key: Country
  value: Cities
}

structure Response {
  @required
  majorCities: CitiesByCountry
}

the output open api spec looks like this (notice how the CitiesByCountry object has lost all traces of the enum and it's values):

{
    "openapi": "3.1.0",
    "info": {
        "title": "ExampleService",
        "version": "1.0.0"
    },
    "paths": {
        "/cities": {
            "get": {
                "operationId": "MajorCitiesByCountry",
                "responses": {
                    "200": {
                        "description": "MajorCitiesByCountry 200 response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MajorCitiesByCountryResponseContent"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "CitiesByCountry": {
                "type": "object",
                "additionalProperties": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "MajorCitiesByCountryResponseContent": {
                "type": "object",
                "properties": {
                    "majorCities": {
                        "$ref": "#/components/schemas/CitiesByCountry"
                    }
                },
                "required": [
                    "majorCities"
                ]
            }
        }
    }
}

Suggested approach

Instead of discarding all enum information, we could leverage the newly added support for the propertyNames JSON Schema and output the CitiesByCountry object like this:

...
    "components": {
        "schemas": {
            "CitiesByCountry": {
                "type": "object",
                "propertyNames": {
                    "enum": ["UK", "US", "DE", "FR"]
                }
                "additionalProperties": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
...

[denisrosca]

If the proposal looks like something that would be accepted, myself or someone from the team I'm working with could try to tackle it in a PR.

[kstich]

Thanks for opening this issue! We'd accept a change along these lines if you or your team is open to contributing it. For this specific feature, it should be gated by the OpenApiVersion.VERSION_3_1_0 configuration.