Skip to content

Commit 2874262

Browse files
jianyexijianye xiruowan
authored and
giromm2ms
committed
Adding lint rules: R4028,R4029,R4030 (Azure#11812)
* add R4028 * update doc (Azure#11843) * update doc * update description * format * add scope Co-authored-by: jianye xi <jianyxi@microsoft.com> Co-authored-by: Ruoxuan Wang <52271048+ruowan@users.noreply.github.com>
1 parent 2e2a17f commit 2874262

File tree

1 file changed

+123
-0
lines changed

1 file changed

+123
-0
lines changed

‎documentation/openapi-authoring-automated-guidelines.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,8 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
109109
| [R4008](#r4008) | [AvoidEmptyResponseSchema](#r4008) | ARM OpenAPI(swagger) specs |
110110
| [R4012](#r4012) | [XmsPageableMustHaveCorrespondingResponse](#r4012) | ARM OpenAPI(swagger) specs |
111111
| [R4013](#r4013) | [IntegerTypeMustHaveFormat](#r4013) | ARM OpenAPI(swagger) specs |
112+
| [R4028](#r4028) | [ValidResponseCodeRequired](#r4028) | ARM OpenAPI(swagger) specs |
113+
| [R4029](#r4029) | [UniqueClientParameterName](#r4029) | ARM OpenAPI(swagger) specs |
112114

113115
#### SDK Warnings
114116

@@ -141,6 +143,7 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
141143
| [R2029](#r2029) | [PageableOperation](#r2029) | ARM and Data plane OpenAPI(swagger) specs |
142144
| [R4006](#r4006) | [DeprecatedXmsCodeGenerationSetting](#r4006) | ARM and Data plane OpenAPI(swagger) specs |
143145
| [R4024](#r4024) | [PreviewVersionOverOneYear](#r4024) | ARM OpenAPI(swagger) specs |
146+
| [R4030](#r4030) | [UniqueXmsExample](#r4030) | ARM OpenAPI(swagger) specs |
144147

145148

146149
### RPaaS Violations
@@ -3082,3 +3085,123 @@ The following would be valid:
30823085
...
30833086
```
30843087
Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rules](#automated-rules) | [ARM](#arm-violations): [Errors](#arm-errors) or [Warnings](#arm-warnings) | [SDK](#sdk-violations): [Errors](#sdk-errors) or [Warnings](#sdk-warnings)
3088+
3089+
### <a name="r4028" ></a>R4028 ValidResponseCodeRequired
3090+
3091+
**Category** : SDK Error
3092+
3093+
**Applies to** : ARM OpenAPI(swagger) specs
3094+
3095+
**Output Message** : There is no declared valid status code.
3096+
3097+
**Description** : Every operation response must contain a valid code like "200","201","202" or "204" which indicates the operation is succeed and it's not allowed that a response schema just contains a "default" code.
3098+
3099+
**Why this rule is important**: If a Swagger just contains "default" status code, this actually means "everything is an error". All track2 SDK will systematically raise an exception at runtime, if there is no declared valid status code.
3100+
3101+
**CreatedAt**: November 23, 2020
3102+
3103+
**LastModifiedAt**: November 23, 2020
3104+
3105+
**How to fix the violation**: Add a valid response code .
3106+
The following would be valid:
3107+
3108+
```json
3109+
...
3110+
"responses": {
3111+
"200": {
3112+
"description": "Succeeded",
3113+
"schema": {
3114+
"$ref": "#/definitions/MySimpleResource"
3115+
}
3116+
},
3117+
"default": {
3118+
"description": "Error response describing why the operation failed.",
3119+
"schema": {
3120+
"$ref": "#/definitions/ErrorResponse"
3121+
}
3122+
}
3123+
}
3124+
}
3125+
...
3126+
```
3127+
Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rules](#automated-rules) | [ARM](#arm-violations): [Errors](#arm-errors) or [Warnings](#arm-warnings) | [SDK](#sdk-violations): [Errors](#sdk-errors) or [Warnings](#sdk-warnings)
3128+
3129+
### <a name="r4029" ></a>R4029 UniqueClientParameterName
3130+
3131+
**Category** : SDK Error
3132+
3133+
**Applies to** : ARM OpenAPI(swagger) specs
3134+
3135+
**Output Message** : Do not have duplicate name of client parameter name, make sure every client parameter name unique.
3136+
3137+
**Description** : This may cause a problem when different swagger files come together. If two APIs with different client name have the same client parameter subscriptionId, but with different reference name in swaggers, the generated model will also have two clients with two client parameters subscriptionId and subscriptionId1 (the latter one has been renamed to avoid collision). We should ensure that the client parameters are all unique in the same API version.
3138+
3139+
**Why this rule is important**: Make sure no conflict in SDK generation.
3140+
3141+
**CreatedAt**: November 30, 2020
3142+
3143+
**LastModifiedAt**: November 30, 2020
3144+
3145+
**How to fix the violation**: Remove duplicate client parameter, ref to the same one.
3146+
The following would be valid:
3147+
3148+
```json
3149+
...
3150+
"/api": {
3151+
"get": {
3152+
"parameters": [
3153+
{
3154+
"$ref": "#/parameters/ApiVersionParameter"
3155+
},
3156+
{
3157+
// ref to the same subcriptionId
3158+
"$ref": "#/parameters/subscriptionIdParameter"
3159+
},
3160+
],
3161+
},
3162+
"patch": [
3163+
{
3164+
"$ref": "#/parameters/ApiVersionParameter"
3165+
},
3166+
{
3167+
"$ref": "#/parameters/subscriptionIdParameter"
3168+
},
3169+
]
3170+
}
3171+
...
3172+
```
3173+
Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rules](#automated-rules) | [ARM](#arm-violations): [Errors](#arm-errors) or [Warnings](#arm-warnings) | [SDK](#sdk-violations): [Errors](#sdk-errors) or [Warnings](#sdk-warnings)
3174+
3175+
### <a name="r4030" ></a>R4030 UniqueXmsExample
3176+
3177+
**Category** : SDK Warning
3178+
3179+
**Applies to** : ARM OpenAPI(swagger) specs
3180+
3181+
**Output Message** : Do not have duplicate name of x-ms-example, make sure every x-ms-example name unique. Duplicate x-ms-example: {ExampleName}
3182+
3183+
**Description** : x-ms-example name should be unique in the same API version.
3184+
3185+
**Why this rule is important**: Duplicate example name will bring trouble for test codegen. For example: hard to config used example.
3186+
3187+
**CreatedAt**: November 30, 2020
3188+
3189+
**LastModifiedAt**: November 30, 2020
3190+
3191+
**How to fix the violation**: Rename duplicate x-ms-example name
3192+
The following would be valid:
3193+
3194+
```json
3195+
...
3196+
"x-ms-examples": {
3197+
"Create resource": {
3198+
"$ref": "./examples/createResource"
3199+
},
3200+
"Update resource":{
3201+
"$ref": "./examples/updateResource"
3202+
}
3203+
3204+
}
3205+
...
3206+
```
3207+
Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rules](#automated-rules) | [ARM](#arm-violations): [Errors](#arm-errors) or [Warnings](#arm-warnings) | [SDK](#sdk-violations): [Errors](#sdk-errors) or [Warnings](#sdk-warnings)

0 commit comments

Comments
 (0)