Add support for summary and kind in tagMetadata decorator

[baywet]

Clear and concise description of the problem

I'd like to be able to specify the tag kind and summary from TypeSpec so it's present in my OpenAPI 3.2.0 description.

@tagMetadata("foo", #{kind: "FooGroup", summary: "all operations that allow doing Foo" })

Should result in

tags:
- name: foo
  summary: "all operations that allow doing Foo" 
  kind: FooGroup

For OpenAPI 3.2.0 (those fields were added with this version)

For earlier versions of OpenAPI, we should add a x-oai- prefix to the fields, so it'll result in something like this.

tags:
- name: foo
  x-oai-summary: "all operations that allow doing Foo" 
  x-oai-kind: FooGroup

For any documentation comment of the newly added API surface:

• summary: "A short summary of the tag, used for display purposes."
• kind: "A machine-readable string to categorize what sort of tag it is. Any string value can be used"

The converter should also support importing those values from OpenAPI to TypeSpec to provide symmetry in the experience.

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[github-actions]

🎯 Issue Triage

Feature request to extend the @tagMetadata decorator to support summary and kind fields introduced in OpenAPI 3.2.0, with x-oai- prefixed extension fields for earlier OpenAPI versions. The converter should also import these values from OpenAPI back to TypeSpec.

Category: Feature Request

Area: emitter:openapi3, lib:openapi, openapi3:converter

🔍 Analysis

• OpenAPI 3.2.0 added summary and kind fields to tag objects
• The @tagMetadata decorator in @typespec/openapi currently supports description and externalDocs, but not summary or kind
• For OpenAPI < 3.2.0, these fields should be emitted as x-oai-summary and x-oai-kind extensions
• The openapi3 converter needs symmetric support to round-trip these values from OpenAPI → TypeSpec
• Affected packages: @typespec/openapi (decorator definition), @typespec/openapi3 (emitter), and the openapi3 converter

📝 Suggested next steps

• Update TagMetadataOptions model in @typespec/openapi to add optional summary and kind fields
• Update the openapi3 emitter to emit summary/kind for OpenAPI 3.2.0 and x-oai-summary/x-oai-kind for earlier versions
• Update the openapi3 converter to import summary, kind, x-oai-summary, and x-oai-kind from tag objects into TypeSpec
• Add/update tests for both emission and conversion paths

Generated by Agentic Triage