fix(openapi3): preserve @tagMetadata tag declaration order in emitted OpenAPI

[Copilot]

When @tagMetadata is applied, tags were emitted in reverse declaration order because TypeSpec decorators execute bottom-up, causing the metadata map to accumulate entries in reverse.

Changes

• packages/openapi3/src/openapi.ts: In resolveDocumentTags, reverse Object.entries(metadata) before iteration so emitted tags match TypeSpec source declaration order.
• packages/openapi3/test/tagmetadata.test.ts: Add explicit ordering tests; update existing parent-field tests whose expected values reflected the old reversed order. Added tests covering:
  • Ordering preservation across multiple @tagMetadata decorators
  • Operation-level tag not defined in @tagMetadata — inserted before tagMetadata-defined tags
  • Operation-level tag also defined in @tagMetadata — emitted once in its tagMetadata-declared position (not duplicated)

Example

@service
@tagMetadata("First", #{description: "First tag"})
@tagMetadata("Second", #{description: "Second tag"})
@tagMetadata("Third", #{description: "Third tag"})
namespace PetStore {}

Before: tags emitted as Third → Second → First
After: tags emitted as First → Second → Third (matching declaration order)

Tag insertion behavior

• Tags used only at the operation level (via @tag) and not declared with @tagMetadata appear first in the output, in the order they are encountered across operations.
• Tags declared with @tagMetadata follow, in TypeSpec source declaration order.
• A tag used at both the operation level and in @tagMetadata is emitted exactly once, at its @tagMetadata-declared position with its metadata.

[baywet]

@copilot add multiple test cases if we don't have them already: one where a tag is used at the operation level, but not defined at the tagMetadata/service level to see where it "inserts" itself. one where a tag is used at the operation level, and defined at the tagMetadata/service level to see where it "inserts" itself.

[pkg-pr-new]

Open in StackBlitz

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

commit: 76ffa16

[Copilot]

@copilot add multiple test cases if we don't have them already: one where a tag is used at the operation level, but not defined at the tagMetadata/service level to see where it "inserts" itself. one w...

Added two new tests in commit 76ffa16:

1. "operation-level tag not defined in @tagMetadata is inserted before tagMetadata tags" — a tag used only via @tag on an operation (not in @tagMetadata) appears first, followed by the @tagMetadata-defined tags.

2. "operation-level tag also defined in @tagMetadata is emitted once in tagMetadata position" — a tag used via @tag on an operation that is also declared with @tagMetadata is not duplicated; it appears exactly once in its @tagMetadata-declared position (with its metadata).

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[markcowl]

I don't think we can take this, as it is a breaking behavior change. If the order of tags is important, I think the best non-breaking short term solution would be to allow arrays in @tagMetadata. I think the longer term solution is probably here: #10771