[Bug]: Operation order is not preserved when @tagMetadata decorator is used

[aelberg]

Describe the bug

Using the openapi3 emitter version 0.66.0.
When the @tagMetadata is not applied on the namespace the Operations are grouped by their tag in the order defined.
When the @tagMetadata decorator is used the tags are reordered alphabetically and the order of tags is no longer preserved.

Reproduction

Without @tagMetadata

Using @tagMetadata

Checklist

• Follow our Code of Conduct
• Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion.
• The provided reproduction is a minimal reproducible example of the bug.

[timotheeguerin]

you are talking about this field only right?

with @tagMetadata

tags:
  - name: Child Widgets
    description: My description
  - name: Widgets
    description: My description

without @tagMetadata

tags:
  - name: Widgets
  - name: Child Widgets

First I do agree this is not good consitencyhowever I think the operation order as in the 2nd one is not a good order to prevent changes(#2293) Any reason you want it that way instead of having it alphabetized?

[aelberg]

Correct using the @tagMetadata decorator is impacting the order that tags are emitted in the openapi spec which impacts the order in SwaggerUI.

As far as controlling the order of operations this is mostly for a "logical" order. Having parent resources appear before child (we could probably group these in the same tag as well but currently we are not).
We also typically have the more commonly used operations towards the top.
We have some utility type operations that are on every api that we typically put at the end.

I know the order can be controlled via SwaggerUI or other interfaces as well so ordering is not guaranteed. I was just surprised to see it change one I started using the tagMetadata as it had always been ordered based on the order of operations in my typespec file previously.

[timotheeguerin]

so just tested and the order isn't actually alphabetized it is the order as defined in the order the decorators run(bottom up)

playground

change the order you get different results.

However as you are finding out decorator order is also confusing and we general try not to rely on it.

[baywet]

Just ran into the same issue today. Here is my playground in case that helps adding context.

The OpenAPI Specification states:

The order of the tags can be used to reflect on their order by the parsing tools.

While ordering is not a hard requirement (not MUST), it's a common practice for tools that do rendering to leverage the tag order to display the information in a specific... order.

I understand the requirement to "layer" the decorators in some context, hence the bottom up parsing. But here, since that data structure clearly maps to OpenAPI concepts, and order is somewhat important, it's counter intuitive to have things reversed.

@timotheeguerin would you mind sharing a couple of pointers about how we could potentially address this aspect please? (is that a core internal language rewrite, or can we tweak a couple of things).

[baywet]

Sharing some notes from out internal discussion, there are a couple of ways this could be addressed:

• new structure with new decorators for tags, based off enums/unions. This is probably the best developer experience, but would require a set of new decorators, updating the import logic, etc... @timotheeguerin will confer with his team to get opinions in, and potentially create a separate issue.
• update tag metadata to accept an array as well. This would probably provide a "subpart" developer experience for people authoring TypeSpec.
• update the emission code to run reverse when emitting the OpenAPI description, so the order of the tag definitions matches the one in TypeSpec. This is probably the cheapest and fastest path to success today. Additionally, the impact is low (most people likely didn't notice the reversal, or don't care about the order) so we could roll this out as a bugfix without requiring an additional emitter option.