Skip to content

Commit bc910ec

Browse files
author
Konrad Jamrozik
authoredJun 21, 2024··
Add new rule: 1050 - ParameterLocationHasChanged; Change behavior of ChangedParameterOrder rule with regards to x-ms-parameter-location (#334)
1 parent 8dd40e9 commit bc910ec

22 files changed

+924
-93
lines changed
 

‎docs/README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,4 +96,6 @@
9696

9797
[1048 - AddedXmsEnum](rules/1048.md)
9898

99-
[1049 - RemovedXmsEnum](rules/1049.md)
99+
[1049 - RemovedXmsEnum](rules/1049.md)
100+
101+
[1050 - ParameterLocationHasChanged](rules/1050.md)

‎docs/rules/1007.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44

55
**Cause**: This is considered a breaking change.
66

7+
**Related rules**
8+
9+
- [1050 - ParameterLocationHasChanged](1050.md)
10+
711
**Change Example**: Parameter `resourceGroupName` is removed in the new version.
812

913
Old specification

‎docs/rules/1042.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44

55
**Cause**: This is considered a breaking change.
66

7+
**Related rules**
8+
9+
- [1050 - ParameterLocationHasChanged](1050.md)
10+
711
**Example**: Parameter order change from `a, b, e` to `a, e, b`.
812

913
Old specification

‎docs/rules/1050.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
### 1050 - ParameterLocationHasChanged
2+
3+
**Description**: Checks whether any parameter's location ([`x-ms-parameter-location`]) is changed from the previous specification.
4+
This is AutoRest-specific rule. Per the example provided in [specifying required parameters and properties],
5+
and per the documentation of [`x-ms-parameter-location`]:
6+
7+
- non-global parameters have implicitly `method` location and this cannot be changed.
8+
- global parameters have implicitly `client` location and this can be changed to `method` via [`x-ms-parameter-location`].
9+
10+
**Cause**: Changing parameter location from `client` to `method` or vice-versa is considered a breaking change.
11+
12+
**Related rules**
13+
14+
- [1007 - RemovedClientParameter](1007.md)
15+
- [1042 - ChangedParameterOrder](1042.md)
16+
17+
**Example**: Parameter `foo` is changed from being non-global parameter to global parameter in the new version,
18+
hence changing its location from `method` to `client`.
19+
20+
Old specification
21+
```json5
22+
{
23+
"swagger": "2.0",
24+
"info": {
25+
"title": "swagger",
26+
"description": "The Azure Management API.",
27+
"version": "2016-12-01",
28+
...
29+
...
30+
"paths": {
31+
"/subscriptions/{subscriptionId}/providers/Microsoft.Contoso/resource1/{a}": {
32+
"get": {
33+
...
34+
...
35+
"parameters": [
36+
{
37+
"name": "foo",
38+
"in": "path",
39+
"type": "string"
40+
}
41+
]
42+
...
43+
...
44+
}
45+
}
46+
...
47+
...
48+
```
49+
50+
New specification
51+
```json5
52+
{
53+
"swagger": "2.0",
54+
"info": {
55+
"title": "swagger",
56+
"description": "The Azure Management API.",
57+
"version": "2016-12-01",
58+
...
59+
...
60+
"paths": {
61+
"/subscriptions/{subscriptionId}/providers/Microsoft.Contoso/resource1/{a}": {
62+
"get": {
63+
...
64+
...
65+
"parameters": [
66+
{
67+
"ref": "#/parameters/foo"
68+
}
69+
]
70+
...
71+
...
72+
}
73+
}
74+
...
75+
...
76+
"parameters": {
77+
"foo": {
78+
"name": "foo",
79+
"in": "path",
80+
"type": "string"
81+
}
82+
}
83+
```
84+
85+
[`x-ms-parameter-location`]: https://github.com/Azure/autorest/blob/765bc784b0cad173d47f931a04724936a6948b4c/docs/extensions/readme.md#x-ms-parameter-location
86+
[specifying required parameters and properties]: https://github.com/Azure/autorest/blob/765bc784b0cad173d47f931a04724936a6948b4c/docs/generate/how-autorest-generates-code-from-openapi.md#specifying-required-parameters-and-properties

‎openapi-diff/src/core/OpenApiDiff.Core/OpenApiDiff.Core.csproj

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
<PropertyGroup>
88
<AssemblyName>OpenApiDiff.Core</AssemblyName>
99
<PackageTags>Microsoft AutoRest</PackageTags>
10-
<LangVersion>7.1</LangVersion>
10+
<LangVersion>7.3</LangVersion>
1111
</PropertyGroup>
1212

1313
<ItemGroup>

‎openapi-diff/src/core/OpenApiDiff/OpenApiDiff.csproj

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
<PackageProjectUrl>https://github.com/Azure/openapi-diff</PackageProjectUrl>
1616
<GeneratePackageOnBuild>True</GeneratePackageOnBuild>
1717
<PackageRequireLicenseAcceptance>False</PackageRequireLicenseAcceptance>
18-
<LangVersion>7.1</LangVersion>
18+
<LangVersion>7.3</LangVersion>
1919
</PropertyGroup>
2020

2121
<ItemGroup>

‎openapi-diff/src/modeler/AutoRest.Swagger.Tests/AutoRest.Swagger.Tests.csproj

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,9 @@
55

66
<PropertyGroup>
77
<TargetFramework>netcoreapp6.0</TargetFramework>
8-
<LangVersion>7.1</LangVersion>
8+
<LangVersion>7.3</LangVersion>
99
</PropertyGroup>
1010

11-
12-
1311
<ItemGroup>
1412
<Content Include="Resource\Swagger\new\added_path.json" />
1513
<Content Include="Resource\Swagger\new\added_readonly_required_property.json" />
@@ -24,9 +22,13 @@
2422
<Content Include="Resource\Swagger\new\operation_check_03.json" />
2523
<Content Include="Resource\Swagger\new\operation_check_04.json" />
2624
<Content Include="Resource\Swagger\new\operation_check_05.json" />
25+
<Content Include="Resource\Swagger\new\global_parameter_order_change.json" />
26+
<Content Include="Resource\Swagger\new\global_parameter_no_order_change.json" />
27+
<Content Include="Resource\Swagger\new\parameter_location_change.json" />
2728
<Content Include="Resource\Swagger\new\param_check_01.json" />
2829
<Content Include="Resource\Swagger\new\removed_definition.json" />
2930
<Content Include="Resource\Swagger\new\removed_operation.json" />
31+
<Content Include="Resource\Swagger\new\removed_parameter.json" />
3032
<Content Include="Resource\Swagger\new\removed_path.json" />
3133
<Content Include="Resource\Swagger\new\required_parameter.json" />
3234
<Content Include="Resource\Swagger\new\response_check_01.json" />
@@ -50,6 +52,10 @@
5052
<Content Include="Resource\Swagger\new\version_check_04.json" />
5153
<Content Include="Resource\Swagger\old\added_readonly_required_property.json" />
5254
<Content Include="Resource\Swagger\old\added_required_property.json" />
55+
<Content Include="Resource\Swagger\old\global_parameter_no_order_change.json" />
56+
<Content Include="Resource\Swagger\old\global_parameter_order_change.json" />
57+
<Content Include="Resource\Swagger\old\parameter_location_change.json" />
58+
<Content Include="Resource\Swagger\old\removed_parameter.json" />
5359
<Content Include="Resource\Swagger\old\recursive_model.json" />
5460
<Content Include="Resource\Swagger\old\changed_operation_id.json" />
5561
<Content Include="Resource\Swagger\old\added_path.json" />
@@ -94,4 +100,4 @@
94100
</ItemGroup>
95101

96102
<ProjectExtensions><VisualStudio><UserProperties /></VisualStudio></ProjectExtensions>
97-
</Project>
103+
</Project>

‎openapi-diff/src/modeler/AutoRest.Swagger.Tests/Resource/Swagger/new/global_parameter_no_order_change.json

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
{
2+
"swagger": 2.0,
3+
"info": {
4+
"title": "global_parameter_no_order_change",
5+
"version": "1.0"
6+
},
7+
"host": "localhost:8000",
8+
"schemes": [ "http", "https" ],
9+
"paths": {
10+
"/api/Parameters": {
11+
"get": {
12+
"tag": [ "Parameters" ],
13+
"operationId": "Parameters_Get",
14+
"produces": [
15+
"text/plain"
16+
],
17+
"parameters": [
18+
{
19+
"$ref": "#/parameters/MethodLocationParam1"
20+
},
21+
{
22+
"$ref": "#/parameters/ClientLocationParam"
23+
},
24+
{
25+
"$ref": "#/parameters/MethodLocationParam2"
26+
},
27+
{
28+
"$ref": "#/parameters/ImplicitLocationParam"
29+
}
30+
]
31+
}
32+
}
33+
},
34+
"parameters": {
35+
"ImplicitLocationParam": {
36+
"name": "implicit_location_param",
37+
"in": "query",
38+
"required": true,
39+
"type": "string",
40+
"description": "Implicit x-ms-parameter-location param"
41+
},
42+
"ClientLocationParam": {
43+
"name": "current_location_param",
44+
"in": "query",
45+
"required": true,
46+
"type": "string",
47+
"description": "client x-ms-parameter-location param",
48+
"x-ms-parameter-location": "client"
49+
},
50+
"MethodLocationParam1": {
51+
"name": "method_location_param_1",
52+
"in": "query",
53+
"required": true,
54+
"type": "string",
55+
"description": "method x-ms-parameter-location param 1",
56+
"x-ms-parameter-location": "method"
57+
},
58+
"MethodLocationParam2": {
59+
"name": "method_location_param_2",
60+
"in": "query",
61+
"required": true,
62+
"type": "string",
63+
"description": "method x-ms-parameter-location param 2",
64+
"x-ms-parameter-location": "method"
65+
}
66+
}
67+
}

‎openapi-diff/src/modeler/AutoRest.Swagger.Tests/Resource/Swagger/new/global_parameter_order_change.json

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
{
2+
"swagger": 2.0,
3+
"info": {
4+
"title": "global_parameter_order_change",
5+
"version": "1.0"
6+
},
7+
"host": "localhost:8000",
8+
"schemes": [ "http", "https" ],
9+
"paths": {
10+
"/api/Parameters": {
11+
"get": {
12+
"tag": [ "Parameters" ],
13+
"operationId": "Parameters_Get",
14+
"produces": [
15+
"text/plain"
16+
],
17+
"parameters": [
18+
{
19+
"$ref": "#/parameters/MethodLocationParam2"
20+
},
21+
{
22+
"$ref": "#/parameters/ImplicitLocationParam"
23+
},
24+
{
25+
"$ref": "#/parameters/MethodLocationParam1"
26+
},
27+
{
28+
"$ref": "#/parameters/ClientLocationParam"
29+
}
30+
]
31+
}
32+
}
33+
},
34+
"parameters": {
35+
"ImplicitLocationParam": {
36+
"name": "implicit_location_param",
37+
"in": "query",
38+
"required": true,
39+
"type": "string",
40+
"description": "Implicit x-ms-parameter-location param"
41+
},
42+
"ClientLocationParam": {
43+
"name": "current_location_param",
44+
"in": "query",
45+
"required": true,
46+
"type": "string",
47+
"description": "client x-ms-parameter-location param",
48+
"x-ms-parameter-location": "client"
49+
},
50+
"MethodLocationParam1": {
51+
"name": "method_location_param_1",
52+
"in": "query",
53+
"required": true,
54+
"type": "string",
55+
"description": "method x-ms-parameter-location param 1",
56+
"x-ms-parameter-location": "method"
57+
},
58+
"MethodLocationParam2": {
59+
"name": "method_location_param_2",
60+
"in": "query",
61+
"required": true,
62+
"type": "string",
63+
"description": "method x-ms-parameter-location param 2",
64+
"x-ms-parameter-location": "method"
65+
}
66+
}
67+
}

‎openapi-diff/src/modeler/AutoRest.Swagger.Tests/Resource/Swagger/new/parameter_location_change.json

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
{
2+
"swagger": 2.0,
3+
"info": {
4+
"title": "parameter_location_change",
5+
"version": "1.0"
6+
},
7+
"host": "localhost:8000",
8+
"schemes": [ "http", "https" ],
9+
"paths": {
10+
"/api/Parameters": {
11+
"get": {
12+
"tag": [ "Parameters" ],
13+
"operationId": "Parameters_Get",
14+
"produces": [
15+
"text/plain"
16+
],
17+
"parameters": [
18+
{
19+
"$ref": "#/parameters/ImplicitFromMethodToClient"
20+
},
21+
{
22+
"$ref": "#/parameters/GlobalFromClientToMethodParam"
23+
},
24+
{
25+
"$ref": "#/parameters/GlobalFromClientToClientParam"
26+
},
27+
{
28+
"name": "from_implicit_global_client_to_implicit_method",
29+
"in": "query",
30+
"type": "string"
31+
}
32+
]
33+
}
34+
}
35+
},
36+
"parameters": {
37+
"ImplicitFromMethodToClient": {
38+
"name": "implicit_from_method_to_client",
39+
"in": "query",
40+
"type": "string"
41+
},
42+
"GlobalFromClientToMethodParam": {
43+
"name": "global_from_client_to_method",
44+
"in": "query",
45+
"type": "string",
46+
"x-ms-parameter-location": "method"
47+
},
48+
"GlobalFromClientToClientParam": {
49+
"name": "global_from_client_to_client",
50+
"in": "query",
51+
"type": "string",
52+
"x-ms-parameter-location": "client"
53+
}
54+
}
55+
}

‎openapi-diff/src/modeler/AutoRest.Swagger.Tests/Resource/Swagger/new/parameter_order_change.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"swagger": 2.0,
33
"info": {
4-
"title": "required_parameter",
4+
"title": "parameter_order_change",
55
"version": "1.0"
66
},
77
"host": "localhost:8000",

0 commit comments

Comments
 (0)
Please sign in to comment.