feat(openapi3): extend annotated enum strategy to unions of literals

[tellnes]

Extends enum-strategy: annotated (#10892, which fixed #5721) to unions of literals. That option previously stopped at enum declarations, so unions of literals still collapsed to a flat enum, dropping variant names, @summary, and docs.

/** Set of known error types. */
union ErrorType {
  /** Common error for a bad request. */
  @summary("CommonBadRequest")
  commonBadRequest: "https://example.com/errors/bad-request",
}

Before: { type: string, enum: ["https://example.com/errors/bad-request"] }

After (with enum-strategy: annotated):

ErrorType:
  description: Set of known error types.
  anyOf:
    - const: https://example.com/errors/bad-request
      title: CommonBadRequest
      description: Common error for a bad request.

Behavior

• Opt-in via the existing option; default output unchanged.
• 3.1.0/3.2.0 only; 3.0.0 falls back and reports the existing enum-strategy-not-supported warning.
• oneOf when the union has @oneOf, else anyOf.
• title from @summary, description from @doc, both omitted when absent, matching the enum handling.
• Non-literal variants (models/scalars) stay as their own members; discriminated unions untouched.

Open question

The option is named enum-strategy but now also covers unions of literals (both are "enumerated types" in OpenAPI terms). I broadened its description rather than renaming it. Happy to add an alias if preferred.

[github-actions]

All changed packages have been documented.

• ✅ @typespec/openapi3

Show changes

@typespec/openapi3 - feature ✏️

Extend the enum-strategy: annotated emitter option to unions of literals. When set to annotated, a union whose variants are literals is emitted as a oneOf/anyOf of const subschemas with per-variant title/description taken from @summary and @doc, instead of collapsing to a single lossy enum. Supported for OpenAPI 3.1.0 and above; emitting with OpenAPI 3.0.0 falls back to the default form and reports a warning.,> ,> For example, the following TypeSpec:,> ,> typespec,> /** Set of known error types. */,> union ErrorType {,> /** Common error for a bad request. */,> @summary("CommonBadRequest"),> commonBadRequest: "https://example.com/errors/bad-request",,> ,> /** The request body could not be parsed. */,> @summary("InvalidBody"),> invalidBody: "https://example.com/errors/invalid-body",,> },> ,> ,> emits:,> ,> yaml,> ErrorType:,> description: Set of known error types.,> anyOf:,> - const: https://example.com/errors/bad-request,> title: CommonBadRequest,> description: Common error for a bad request.,> - const: https://example.com/errors/invalid-body,> title: InvalidBody,> description: The request body could not be parsed.,> ,> ,> Use @oneOf on the union to emit oneOf instead of anyOf.