Skip to content

Commit 285beb6

Browse files
sanjaiganeshsanjaiganesh
authored
added new rules (#11677)
1 parent b6d64aa commit 285beb6

File tree

1 file changed

+94
-2
lines changed

1 file changed

+94
-2
lines changed

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

Lines changed: 94 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,8 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
150150
| Id | Rule Name | Applies to |
151151
| --- | --- | --- |
152152
| [R4023](#r4023) | [RPaasPutLongRunningOperation201Only](#r4023) | ARM OpenAPI(swagger) specs |
153+
| [R4025](#r4025) | [RPaasDeleteLongRunningOperation202Only](#r4025) | ARM OpenAPI(swagger) specs |
154+
| [R4026](#r4026) | [RPaasPostLongRunningOperation202Only](#r4026) | ARM OpenAPI(swagger) specs |
153155

154156
### Documentation
155157

@@ -2929,13 +2931,13 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul
29292931

29302932
**Output Message** : [RPaaS] Only 201 is the supported response code for PUT async response
29312933

2932-
**Description** : An async PUT operation response include status code 201 with Azure-async-operation header. Must also support status code 200, for simple updates that can be completed synchronously (ex: tags). Operation must also add "x-ms-long-running-operation and x-ms-long-running-operation-options" to describe how the long running operation is tracked.
2934+
**Description** : An async PUT operation response include status code 201 with 'Azure-async-operation' header. Must also support status code 200, for simple updates that can be completed synchronously (ex: tags). Operation must also add "x-ms-long-running-operation and x-ms-long-running-operation-options" to mark that it is a long running operation (in case of 201) and how it is tracked (Azure-async-operation header).
29332935

29342936
**CreatedAt**: August 10, 2020
29352937

29362938
**LastModifiedAt**: August 10, 2020
29372939

2938-
**Why this rule is important**: RPaaS only supports 201 for async operations. This is enforced at runtime via swagger validation.
2940+
**Why this rule is important**: RPaaS only supports 201 for async PUT operations. This is enforced at runtime via swagger validation.
29392941

29402942
**How to fix the violation**: Add the following for async PUT operations.
29412943

@@ -2990,3 +2992,93 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul
29902992

29912993
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)
29922994

2995+
### <a name="r4025"></a>R4025 RPaasDeleteLongRunningOperation202Only
2996+
2997+
**Category** : RPaaS Error
2998+
2999+
**Applies to** : ARM OpenAPI(swagger) specs
3000+
3001+
**Output Message** : [RPaaS] DELETE async supports
3002+
3003+
**Description** : An async DELETE operation response include status code 202 with 'Location' header. Must support status code 200 if operation can be completed synchronously. Must support 204 (resource doesn't exists). Operation must also add "x-ms-long-running-operation and x-ms-long-running-operation-options" to mark that it is a long running operation (in case of 202) and how it is tracked (Location header).
3004+
3005+
**CreatedAt**: November 12, 2020
3006+
3007+
**LastModifiedAt**: November 12, 2020
3008+
3009+
**Why this rule is important**: RPaaS only supports 202 for async DELETE operations. This is enforced at runtime via swagger validation.
3010+
3011+
**How to fix the violation**: Add the following for async DELETE operations.
3012+
3013+
The following would be valid:
3014+
3015+
```json
3016+
...
3017+
"responses": {
3018+
"202": {
3019+
"description": "Delete operation accepted",
3020+
},
3021+
"200": {
3022+
"description": "Delete operation succeeded"
3023+
},
3024+
"204": {
3025+
"description": "Resource doesn't exist. Delete operation completed."
3026+
},
3027+
"default": {
3028+
"description": "Error response describing why the operation failed.",
3029+
"schema": {
3030+
"$ref": "#/definitions/ErrorResponse"
3031+
}
3032+
}
3033+
},
3034+
"x-ms-long-running-operation": true,
3035+
"x-ms-long-running-operation-options": {
3036+
"final-state-via": "location"
3037+
}
3038+
...
3039+
```
3040+
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)
3041+
3042+
### <a name="r4026"></a>R4026 RPaasPostLongRunningOperation202Only
3043+
3044+
**Category** : RPaaS Error
3045+
3046+
**Applies to** : ARM OpenAPI(swagger) specs
3047+
3048+
**Output Message** : [RPaaS] POST async supports
3049+
3050+
**Description** : An async POST operation response include status code 202 with 'Location' header. Must support status code 200 if operation can be completed synchronously. Operation must also add "x-ms-long-running-operation and x-ms-long-running-operation-options" to mark that it is a long running operation (in case of 202) and how it is tracked (Location header).
3051+
3052+
**CreatedAt**: November 12, 2020
3053+
3054+
**LastModifiedAt**: November 12, 2020
3055+
3056+
**Why this rule is important**: RPaaS only supports 202 for async POST operations. This is enforced at runtime via swagger validation.
3057+
3058+
**How to fix the violation**: Add the following for async POST operations.
3059+
3060+
The following would be valid:
3061+
3062+
```json
3063+
...
3064+
"responses": {
3065+
"202": {
3066+
"description": "Operation accepted",
3067+
},
3068+
"200": {
3069+
"description": "Operation completed"
3070+
},
3071+
"default": {
3072+
"description": "Error response describing why the operation failed.",
3073+
"schema": {
3074+
"$ref": "#/definitions/ErrorResponse"
3075+
}
3076+
}
3077+
},
3078+
"x-ms-long-running-operation": true,
3079+
"x-ms-long-running-operation-options": {
3080+
"final-state-via": "location"
3081+
}
3082+
...
3083+
```
3084+
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)