feat(openapi3): add opt-in enum-style option for annotated enums

[timotheeguerin]

Fixes #5721

Adds a new opt-in enum-style emitter option to @typespec/openapi3. When set to annotated, TypeSpec enums are emitted as OpenAPI 3.1.1 annotated enumerations — a oneOf of const subschemas with per-member title and description taken from @summary and @doc on each enum member. This preserves member-level documentation that otherwise gets dropped by the default enum keyword form.

Behavior

• Default value is default; existing emitter output is unchanged.
• annotated is supported on OpenAPI 3.1.0 and 3.2.0 (which support const).
• For OpenAPI 3.0.0, annotated falls back to the default form and a new enum-style-not-supported warning is reported.
• Applies only to TypeSpec enum declarations; unions of literals are unchanged.
• Outer enum-level constraints (@doc, @summary, etc.) are still applied to the wrapping schema via applyConstraints.

Example

/** Type of pet. */
enum PetType {
  /** A loyal canine companion. */
  @summary("Dog")
  Dog: "dog",

  /** A self-sufficient feline. */
  @summary("Cat")
  Cat: "cat",
}

With enum-style: annotated and OpenAPI 3.1.0/3.2.0:

PetType:
  description: Type of pet.
  oneOf:
    - const: dog
      title: Dog
      description: A loyal canine companion.
    - const: cat
      title: Cat
      description: A self-sufficient feline.

Files changed

• packages/openapi3/src/lib.ts — EnumStyle type, enum-style option (+ JSON schema), and enum-style-not-supported warning diagnostic.
• packages/openapi3/src/openapi.ts — enumStyle propagated into ResolvedOpenAPI3EmitterOptions; warning emitted in resolveOptions when paired with 3.0.0.
• packages/openapi3/src/schema-emitter-3-1.ts — annotated branch in enumSchema (3.2 inherits).
• packages/openapi3/test/enums.test.ts — 13 new tests covering 3.1/3.2 annotated form (string, number, mixed, with/without docs, default unchanged), 3.0.0 fallback, and warning emission.
• .chronus/changes/openapi3-enum-style-annotated-*.md — feature changelog entry.

[pkg-pr-new]

Open in StackBlitz

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

commit: 453f7a9

[github-actions]

All changed packages have been documented.

• ✅ @typespec/openapi3

Show changes

@typespec/openapi3 - feature ✏️

Add opt-in enum-strategy emitter option to emit TypeSpec enums as annotated enumerations (a oneOf of const subschemas with per-member title/description). Supported for OpenAPI 3.1.0 and above; emitting with OpenAPI 3.0.0 falls back to the default form and reports a warning.,> ,> yaml,> options:,> "@typespec/openapi3":,> enum-strategy: annotated,> ,> ,> For example, the following TypeSpec:,> ,> typespec,> /** Type of pet. */,> enum PetType {,> /** A loyal canine companion. */,> @summary("Dog"),> Dog: "dog",,> ,> /** A self-sufficient feline. */,> @summary("Cat"),> Cat: "cat",,> },> ,> ,> emits:,> ,> yaml,> PetType:,> description: Type of pet.,> oneOf:,> - const: dog,> title: Dog,> description: A loyal canine companion.,> - const: cat,> title: Cat,> description: A self-sufficient feline.,>

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[markcowl]

I wonder if @summary exactly corresponds with title, but otherwise, this looks great

[timotheeguerin]

Yeah summary is title in openapi