Added new rule LroAzureAsyncOperationHeader

docs/lro-azure-async-operation-header.md

@@ -0,0 +1,67 @@
+# LroAzureAsyncOperationHeader
+
+## Category
+
+ARM Error
+
+## Applies to
+
+ARM OpenAPI(swagger) specs
+
+## Related ARM Guideline Code
+
+- RPC-Async-V1-06
+
+## Output Message
+
+A 202 response should include an Azure-AsyncOperation response header.
+
+## Description
+
+Azure-AsyncOperation header must be supported for all async operations that return 202.
+
+## CreatedAt
+
+Oct 11, 2024
+
+## How to fix the violation
+
+Adding the Azure-AsyncOperation header schema to the 202 response header schema.
+
+## Good Example
+
+```json
+  "/api/configServers": {
+    put: {
+      operationId: "ConfigServers_Update",
+      responses: {
+        202: {
+          description: 'Accepted',
+          headers: {
+            'Azure-AsyncOperation': {
+              type: 'string',
+            },
+          },
+        },
+      },
+    },
+  },
+```
+
+## Bad Example
+
+```json
+  "/api/configServers": {
+    put: {
+      operationId: "ConfigServers_Update",
+      responses: {
+        "202": {
+          description: "Success",
+          headers: {
+            //No Azure-AsyncOperation header 
+          },
+        },
+      },
+    },
+  },
+```

docs/rules.md

@@ -495,6 +495,12 @@ For Data plane spec, the allowed response status codes for a long DELETE operati
 
 Please refer to [long-running-response-status-code-data-plane.md](./long-running-response-status-code-data-plane.md) for details.
 
+### LroAzureAsyncOperationHeader
+
+Azure-AsyncOperation header must be supported for all async operations that return 202.
+
+Please refer to [lro-azure-async-operation-header.md](./lro-azure-async-operation-header.md) for details.
+
 ### LroErrorContent
 
 Error response content of long running operations must follow the error schema provided in the common types v2 and above.

packages/rulesets/generated/spectral/az-arm.js

@@ -3301,6 +3301,20 @@ const ruleset = {
                 function: provisioningState,
             },
         },
+        LroAzureAsyncOperationHeader: {
+            rpcGuidelineCode: "RPC-Async-V1-06",
+            description: "Azure-AsyncOperation header must be supported for all async operations that return 202.",
+            message: "{{description}}",
+            severity: "error",
+            formats: [oas2],
+            given: "$.paths[*][*].responses[?(@property == '202')]",
+            then: {
+                function: hasHeader,
+                functionOptions: {
+                    name: "Azure-AsyncOperation",
+                },
+            },
+        },
         LroLocationHeader: {
             rpcGuidelineCode: "RPC-Async-V1-07",
             description: "Location header must be supported for all async operations that return 202.",

packages/rulesets/src/spectral/az-arm.ts

@@ -158,6 +158,22 @@ const ruleset: any = {
       },
     },
 
+    // RPC Code: RPC-Async-V1-06
+    LroAzureAsyncOperationHeader: {
+      rpcGuidelineCode: "RPC-Async-V1-06",
+      description: "Azure-AsyncOperation header must be supported for all async operations that return 202.",
+      message: "{{description}}",
+      severity: "error",
+      formats: [oas2],
+      given: "$.paths[*][*].responses[?(@property == '202')]",
+      then: {
+        function: hasheader,
+        functionOptions: {
+          name: "Azure-AsyncOperation",
+        },
+      },
+    },
+
     // RPC Code: RPC-Async-V1-07
     LroLocationHeader: {
       rpcGuidelineCode: "RPC-Async-V1-07",

packages/rulesets/src/spectral/test/lro-azure-async-operation-header.test.ts

@@ -0,0 +1,158 @@
+import { Spectral } from "@stoplight/spectral-core"
+import linterForRule from "./utils"
+
+let linter: Spectral
+
+beforeAll(async () => {
+  linter = await linterForRule("LroAzureAsyncOperationHeader")
+  return linter
+})
+
+const ERROR_MESSAGE = "Azure-AsyncOperation header must be supported for all async operations that return 202."
+
+test("LroAzureAsyncOperationHeader should find no errors", () => {
+  const myOpenApiDocument = {
+    swagger: "2.0",
+    paths: {
+      "/foo1/operations": {
+        get: {
+          operationId: "foo_get",
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Accepted",
+              headers: {
+                "Azure-AsyncOperation": {
+                  description: "The URL where the status of the asynchronous operation can be checked.",
+                  type: "string",
+                },
+              },
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+        post: {
+          operationId: "foo_post",
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Accepted",
+              headers: {
+                "Azure-asyncoperation": {
+                  description: "The URL where the status of the asynchronous operation can be checked.",
+                  type: "string",
+                },
+              },
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+        put: {
+          operationId: "foo_put",
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Accepted",
+              headers: {
+                "azure-asyncOperation": {
+                  description: "The URL where the status of the asynchronous operation can be checked.",
+                  type: "string",
+                },
+              },
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+      },
+    },
+  }
+  return linter.run(myOpenApiDocument).then((results) => {
+    expect(results.length).toBe(0)
+  })
+})
+
+test("LroAzureAsyncOperationHeader should find errors with no Azure-AsyncOperation header", () => {
+  const myOpenApiDocument = {
+    swagger: "2.0",
+    paths: {
+      "/foo1/operations": {
+        get: {
+          operationId: "foo_get",
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Accepted",
+              headers: {
+                Location: {
+                  description: "The URL where the status of the asynchronous operation can be checked.",
+                  type: "string",
+                },
+              },
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+        post: {
+          operationId: "foo_post",
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Accepted",
+              headers: {},
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+        put: {
+          operationId: "foo_put",
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Accepted",
+              headers: {
+                azureasyncOperation: {
+                  description: "The URL where the status of the asynchronous operation can be checked.",
+                  type: "string",
+                },
+              },
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+      },
+    },
+  }
+  return linter.run(myOpenApiDocument).then((results) => {
+    expect(results.length).toBe(3)
+    expect(results[0].path.join(".")).toBe("paths./foo1/operations.get.responses.202.headers")
+    expect(results[0].message).toEqual(ERROR_MESSAGE)
+    expect(results[1].path.join(".")).toBe("paths./foo1/operations.post.responses.202.headers")
+    expect(results[1].message).toEqual(ERROR_MESSAGE)
+    expect(results[2].path.join(".")).toBe("paths./foo1/operations.put.responses.202.headers")
+    expect(results[2].message).toEqual(ERROR_MESSAGE)
+  })
+})