Azure / Azure/typespec-azure

[Bug]: Swagger emitter should make APIVersionParameter a client level location

Open
#2,578 1 comment 2 reactions 0 assignees View on GitHub
bug lib:azure-core triaged:core
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

### Describe the bug

A generated Swagger has this:
```json
"Azure.Core.Foundations.ApiVersionParameter": {
"name": "api-version",
"in": "query",
"description": "The API version to use for this operation.",
"required": true,
"type": "string",
"minLength": 1,
"x-ms-parameter-location": "method",
"x-ms-client-name": "apiVersion"
}
```

That's incorrect, the API version parameter is always at the client level. This breaks the Swagger breaking change detection tool, because now it considers a change in APIVersionParameter position as breaking. Given that in the Swagger emitter, usage of templates makes the APIVersionParameter always first, it signals a breaking change in any operation that didn't hve their Swagger starting with APIVersionParameter.

See https://github.com/Azure/azure-rest-api-specs/pull/33855/checks?check_run_id=41033821331 as an example

### Reproduction

Generate a Swagger from a TypeSpec that uses Azure.Core.Foundations.ApiVersionParameter from a template of Azre.Core.

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/azure/typespec-azure/blob/main/CODE_OF_CONDUCT.md)
- [x] Check that this issue is about the Azure libraries for typespec. For bug in the typespec language or core libraries file it in the [TypeSpec repo](https://github.com/Microsoft/TypeSpec/issues/new/choose)
- [x] Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
- [x] The provided reproduction is a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) of the bug.

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the Swagger generation from a TypeSpec template that uses Azure.Core.Foundations.ApiVersionParameter, then trace the Swagger emitter path that assigns its parameter location. Done means the generated parameter uses the client-level location rather than "method" and the breaking-change detection case no longer reports a position change.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.