Multiple specs error with latest autorest due tag config multiple defination

chamons commented 3 years ago

These specs:

specification/softwareplan/resource-manager/readme.md and specification/desktopvirtualization/resource-manager/readme.md and specification/iotcentral/resource-manager/readme.md and specification/hybriddatamanager/resource-manager/readme.md fail when processed with autorest 3.1.0-dev.2.

Discussions with @timotheeguerin suggests that they are issues in the swagger redefining tags:

it used to test release_2 but now is testing release_1 with that $ref as an attribute

Builds showing issue:

https://dev.azure.com/azure-sdk/public/_build/results?buildId=748819&view=logs&j=1a6ae1a5-56d5-51f8-8f8d-f67115b54b1a&t=937f187a-1519-5cb7-77a5-47832257e788

https://dev.azure.com/azure-sdk/public/_build/results?buildId=751474&view=logs&j=ac074fc7-7a1e-5636-a7ea-9c59e123a9ef&t=79ef76a9-b720-5417-f045-9a3cbd25ad16

chamons commented 3 years ago

cc @datr93 and @njuCZ who are the latest people who's touched those files.

timotheeguerin commented 3 years ago

The issue in those specs is that the tag config is being defined twice globally in the file. This used to not be a problem as the later ones would get ignored but now the later one will override the first one.

In those specs this result in having multiple tags config being read and so including multiple version specs together.

See for example in this readme specification/softwareplan/resource-manager/readme.md

``` yaml
openapi-type: arm
tag: package-2019-06-01-preview

Tag: package-2019-06-01-preview

These settings apply only when --tag=package-2019-06-01-preview is specified on the command line.

input-file:
  - Microsoft.SoftwarePlan/preview/2019-06-01-preview/softwareplan.json

openapi-type: arm
tag: package-2019-12-01

Tag: package-2019-12-01

These settings apply only when --tag=package-2019-12-01 is specified on the command line.

input-file:
  - Microsoft.SoftwarePlan/stable/2019-12-01/softwareplan.json



It does the following:
1. Set `tag: package-2019-06-01-preview`
2. Condition match so it include `2019-06-01-preview/softwareplan.json`
3. Set `tag: package-2019-12-01`
4. Condition match so it include `2019-12-01/softwareplan.json`

### Solution

Remove the 2nd tag override. It shouldn't be here. Not sure if it something was trying to be achieved with this or this is some copy paste leftover

chamons commented 3 years ago

Adding /specification/iotcentral/resource-manager/readme.md and cc @leni-msft

chamons commented 3 years ago

Adding specification/hybriddatamanager/resource-manager/readme.md and cc @prtank and @ t-prta

prtank commented 3 years ago

Hey, could you point me to some documentation about how these tags should be defined?

timotheeguerin commented 3 years ago

@prtank I explained in this reply the problem and solution. The issue is always the same. The tag gets redefined twice and the 2nd (for the same behavior as before) needs to be removed

https://github.com/Azure/azure-rest-api-specs/issues/13147#issuecomment-785322386

prtank commented 3 years ago

Hi Timothee, I did see your comment on having only a single tag in the file. I should've been clearer, could you tell me how the tags work and what they're meant to signify?

timotheeguerin commented 3 years ago

tag is not something that autorest really cares about. It is just a convention used that applies to this file. They act like any other configuration properties and here it is used to configure which input-files to include. Some yaml block have a condition on a specific tag (yaml $(tag) == 'package-2019-12-01') and specify for that tag to load the swagger specs for that version(Microsoft.SoftwarePlan/stable/2019-12-01/softwareplan.json).

Or was your question more on how does the configuration in autorest works?

prtank commented 3 years ago

If the tags are used to specify which file to pick how should multiple API versions be handled? I remember adding the second tag while adding the second API version.

timotheeguerin commented 3 years ago

So before the way it used to read the config the second tag assignment was just being ignore the first one had priority. so it was just like if it was not there.

The config file can be seen as just executing some code and assigning variables. with block condition being if statement.

Not exactly sure what you wanted to do for multi api. You can still have multiple tag condition to load the correct input-file depending on the --tag passed via the cli or default to the one on top if not provided.

So the markdown would look like this

``` yaml
openapi-type: arm
tag: package-2019-06-01-preview

Tag: package-2019-06-01-preview

These settings apply only when --tag=package-2019-06-01-preview is specified on the command line.

input-file:
  - Microsoft.SoftwarePlan/preview/2019-06-01-preview/softwareplan.json

Tag: package-2019-12-01

These settings apply only when --tag=package-2019-12-01 is specified on the command line.

input-file:
  - Microsoft.SoftwarePlan/stable/2019-12-01/softwareplan.json

prtank commented 3 years ago

Thanks for the details Timothee. I have raised PR Fix issue 13147 for HybridDataManager#13296 with the change

prtank commented 3 years ago

Hey Timothee, I see that the PR has been merged. Can i consider this issue closed for HybridDataManager?

Azure / azure-rest-api-specs