[openapi3] add enum-mode option for annotated enums in 3.1+

[timotheeguerin]

Summary

Fixes #5721

Adds an opt-in enum-mode emitter option to @typespec/openapi3. When set to "annotated", enums are rendered using the OpenAPI 3.1 annotated enumerations pattern — a oneOf of single-const subschemas with per-member title/description pulled from @summary/@doc:

PetType:
  oneOf:
    - type: string
      const: dog
      description: A four-legged friend
    - type: string
      const: cat

The default "enum" preserves today's flat enum: [...] output. The option is silently ignored for OpenAPI 3.0 since const annotated enums are a 3.1 construct. 3.2 inherits the 3.1 emitter and so picks the behavior up automatically.

Test plan

• pnpm -F @typespec/openapi3 build — clean
• pnpm -F @typespec/openapi3 test — 2532 tests pass, including 5 new cases:
  • String enum with @doc → description on each subschema
  • Numeric enum with @summary → title on each subschema
  • Unannotated members → bare {type, const} subschemas
  • Enum-level @doc still applied to the wrapping schema
  • OpenAPI 3.0 + enum-mode: annotated → option ignored (regression guard)

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/openapi3@10893

commit: 06a2b76

[github-actions]

All changed packages have been documented.

• ✅ @typespec/openapi3

Show changes

@typespec/openapi3 - feature ✏️

Add enum-mode emitter option for OpenAPI 3.1+. When set to "annotated", enums are emitted using the annotated enumerations pattern (oneOf of single-const subschemas with title/description from @summary/@doc on each member). The default "enum" preserves the existing flat enum: [...] output. The option has no effect on OpenAPI 3.0.,> ,> yaml,> options:,> "@typespec/openapi3":,> enum-mode: annotated,> openapi-versions: ["3.1.0"],>

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension