Improve support for OpenAPI enum items that contain documentation

[BDQ]

Today, if I use the following Smithy enum definition:

@documentation("The status of the enrollment request.")
enum EnrollmentStatus {
  @documentation("The enrollment request is pending review.")
  PENDING = "PENDING",
  @documentation("The enrollment request has been approved.")
  APPROVED = "APPROVED",
  @documentation("The enrollment request has been rejected.")
  REJECTED = "REJECTED"
}

The following OpenAPI output will be produced, as can be seen below, the per item documentation lines are lost:

{
    "EnrollmentStatus": {
        "type": "string",
        "description": "The status of the enrollment. Only Stedi can set or update this property.",
        "enum": [
            "PENDING",
            "APPROVED",
            "REJECTED"
        ]
    }
}

Using OAS 3.1.x (and JSON Schema 2020-12) enums can be defined with oneOf along with const to allow documentation to included for each item, for example:

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"properties": {
		"status": {
			"type": "string",
			"description": "The status of the enrollment request.",
			"oneOf": [
				{
					"const": "PENDING",
					"description": "The enrollment request is pending."
				},
				{
					"const": "APPROVED",
					"description": "The enrollment request has been approved."
				},
				{
					"const": "REJECTED",
					"description": "The enrollment request has been rejected."
				}
			]
		}
	}
}

It would be great if we could have the same support in the openapi plugin.

[nated0g]

To help move this forward since it would be really useful for us:

One possible approach might be to handle this similarly to how unions and maps are configured in the OpenAPI plugin, with the unionStrategy and mapStrategy configuration settings. (Though maybe this would additionally need to be scoped to specific versions of JsonSchema and open-api?)

A potential solution could be:

1. A new configuration setting called enumStrategy that supports:
   • enum (current default behavior using simple array-formatted string enum)
   • oneOf (new behavior using oneOf with const values to preserve member docs)

It seems like at least the following would need to be updated (probably I am missing some other things):

• add enumStrategy to JsonSchemaConfig:
  https://github.com/smithy-lang/smithy/blob/main/smithy-jsonschema/src/main/java/software/amazon/smithy/jsonschema/JsonSchemaConfig.java#L22

• update the handling of handling of enum trait:
  https://github.com/smithy-lang/smithy/blob/main/smithy-jsonschema/src/main/java/software/amazon/smithy/jsonschema/JsonSchemaShapeVisitor.java#L320-L322, probably to be similar to how the oneOf implementation for unions is handled: https://github.com/smithy-lang/smithy/blob/main/smithy-jsonschema/src/main/java/software/amazon/smithy/jsonschema/JsonSchemaShapeVisitor.java#L234-L245

Sharing these notes in case they're helpful to whoever ends up picking this up

[yasmewad]

Yes, we are aligned with the approach. We are open to a PR contribution for this.