OpenAPI-diff should flag changes in the tags for an operation

[mikekistler]

Some tooling uses the operation tags to group or namespace the operations in an API definition. SwaggerUI is one example, but many other tools do as well.

For this reason, OpenAPI diff should detect and report any change in the array of tags specified for an operation. The message should be a warning since this change does not impact the "on the wire" behavior of the API.

A real-life example that tripped up Terraform generation is #34736.

[mikekistler]

@mikeharder assigning this to you for your awareness, but feel free to reassign or unassign as you see fit.

[mikeharder]

@mikekistler: In my experience, warnings are nearly useless since they are usually ignored. Do you believe this warning would be different? Or should this be an error?

[mikekistler]

I am fine with making it an error. Some teams might complain about this but I agree that leaving it as a warning risks that it will be ignored.

[mikeharder]

@mikekistler: Can you point to the exact problem in PR #34736? Or provide a simpler example?

[mikekistler]

In the original API, the RecordSets_List operation is:

    "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/privateDnsZones/{privateZoneName}/{recordType}": {
      "get": {
        "tags": [
          "RecordSets"
        ],
        "operationId": "RecordSets_ListByType", 
        "description": "Lists the record sets of a specified type in a Private DNS zone.",

and in the new API it is:

    "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/privateDnsZones/{privateZoneName}/aLL": {
      "get": {
        "operationId": "RecordSets_List",
        "tags": [ 
          "PrivateZones"
        ],  
        "description": "Lists all record sets in a Private DNS zone.",

Note that the tags are different. This is what should be flagged.

[mikeharder]

@mikekistler: I don't know much about the openapi-diff architecture. Are you requesting a new rule be added, named something like 1051 - TagsHasChanged, similar to this PR (latest adding a new rule):

Add new rule: 1050 - ParameterLocationHasChanged; Change behavior of ChangedParameterOrder rule with regards to x-ms-parameter-location (#334)

Or would this be a modification to an existing rule? If so, which rule(s)?

[mikekistler]

This would be a new rule, similar to the PR you linked.