Add pageable rule

docs/pageable-operations.md

@@ -0,0 +1,134 @@
+# PageableOperations
+
+## Description
+
+This rule appears when you define a get operation, and its response schema has a property that is an array. The operation might be pageable.
+
+## How to fix
+
+Add an `x-ms-pageable` extension to the operation.
+
+## Effect on generated code
+
+### Before
+
+#### Spec
+
+```json5
+…
+    "paths": {
+        "/plants": {
+            "get": {
+                "operationId": "Stuff_List",
+                "responses": {
+                    "200": {
+                        "schema": {
+                            "$ref": "#/definitions/StuffList"
+                        }
+                    }
+                }
+            }
+        }
+    }
+…
+    "definitions": {
+        "StuffList": {
+            "type": "object",
+            "properties": {
+                "value": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/Stuff"
+                    }
+                },
+                "nextLink": {
+                    "type": "string",
+                }
+            }
+        },
+        "Stuff": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                },
+            }
+        }
+    }
+…
+```
+
+#### Generated code
+
+```csharp
+public static ProductResult GetMultiplePages(this IPagingOperations operations, string clientRequestId = default(string), PagingGetMultiplePagesOptions pagingGetMultiplePagesOptions = default(PagingGetMultiplePagesOptions))
+{
+    return operations.GetMultiplePagesAsync(clientRequestId, pagingGetMultiplePagesOptions).GetAwaiter().GetResult();
+}
+```
+
+### After
+
+#### Spec
+
+```json5
+…
+    "paths": {
+        "/plants": {
+            "get": {
+                "operationId": "Stuff_List",
+                "responses": {
+                    "200": {
+                        "schema": {
+                            "$ref": "#/definitions/StuffList"
+                        }
+                    }
+                }
+                "x-ms-pageable": {
+                    "nextLinkName": "nextLink"
+                }
+            }
+        }
+    }
+…
+    "definitions": {
+        "StuffList": {
+            "type": "object",
+            "properties": {
+                "value": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/Stuff"
+                    }
+                },
+                "nextLink": {
+                    "type": "string",
+                }
+            }
+        },
+        "Stuff": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                },
+            }
+        }
+    }
+…
+```
+
+#### Generated code
+
+```csharp
+public static IPage<Product> GetMultiplePages(this IPagingOperations operations, string clientRequestId = default(string), PagingGetMultiplePagesOptions pagingGetMultiplePagesOptions = default(PagingGetMultiplePagesOptions))
+{
+    return operations.GetMultiplePagesAsync(clientRequestId, pagingGetMultiplePagesOptions).GetAwaiter().GetResult();
+}
+…
+public static IPage<Product> GetMultiplePagesNext(this IPagingOperations operations, string nextPageLink, string clientRequestId = default(string), PagingGetMultiplePagesOptions pagingGetMultiplePagesOptions = default(PagingGetMultiplePagesOptions))
+{
+    return operations.GetMultiplePagesNextAsync(nextPageLink, clientRequestId, pagingGetMultiplePagesOptions).GetAwaiter().GetResult();
+}
+}
+```

src/typescript/azure-openapi-validator/index.ts

@@ -7,6 +7,7 @@ import { Message } from "../jsonrpc/types";
 import { rules, OpenApiTypes, MergeStates } from "./rule";
 
 // register rules
+require("./rules/PageableOperation");
 require("./rules/DescriptionMustNotBeNodeName");
 require("./rules/ControlCharactersAreNotAllowed");
 require("./rules/ArraySchemaMustHaveItems");

src/typescript/azure-openapi-validator/rules/PageableOperation.ts

@@ -0,0 +1,39 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import { MergeStates, OpenApiTypes, rules } from '../rule';
+export const PageableOperation: string = "PageableOperation";
+
+const jp = require('jsonpath');
+
+rules.push({
+  id: "R2029",
+  name: PageableOperation,
+  severity: "warning",
+  category: "SDKViolation",
+  mergeState: MergeStates.composed,
+  openapiType: OpenApiTypes.arm | OpenApiTypes.dataplane,
+  appliesTo_JsonQuery: "$.paths[?(@.get)]",
+  run: function* (doc, node, path) {
+    const operations = Object.keys(node);
+    const getKey = operations.find(key => {
+      return key.toLowerCase() === 'get';
+    });
+
+    const schemaRef = node[getKey]['responses']['200']['schema']['$ref'];
+    const schemaPath: string[] = (<string>schemaRef).split('/');
+    const schemaProperties = doc.definitions[schemaPath[2]].properties;
+
+    const valueKey = Object.keys(schemaProperties).find(key => {
+      return key.toLowerCase() === 'value';
+    });
+
+    if (valueKey != undefined) {
+      if (schemaProperties[valueKey].type === 'array') {
+        yield { message: `Based on the response model schema, operation '${node[getKey].operationId}' might be pageable. Consider adding the x-ms-pageable swagger extension.`, location: path.concat(getKey) };
+
+      }
+    }
+  }
+});

src/typescript/azure-openapi-validator/tests/composite-azure-test.ts

@@ -12,11 +12,18 @@ import {
   collectTestMessagesFromValidator
 } from './utilities/tests-helper';
 import { DescriptionMustNotBeNodeName } from '../rules/DescriptionMustNotBeNodeName';
+import { PageableOperation } from '../rules/PageableOperation';
 
 @suite class CompositeAzureTests {
   @test async "description should not be property name"() {
     const fileName: string = 'DescriptionSameAsPropertyName.json';
     const messages: Message[] = await collectTestMessagesFromValidator(fileName, OpenApiTypes.arm, MergeStates.composed);
     assertValidationRuleCount(messages, DescriptionMustNotBeNodeName, 2);
   }
+
+  @test async "operations returning a model including an array might be pageable"() {
+    const fileName: string = 'PageableOperation.json';
+    const messages: Message[] = await collectTestMessagesFromValidator(fileName, OpenApiTypes.arm, MergeStates.composed);
+    assertValidationRuleCount(messages, PageableOperation, 1);
+  }
 }

src/typescript/azure-openapi-validator/tests/resources/PageableOperation.json

@@ -0,0 +1,60 @@
+{
+    "swagger": "2.0",
+    "info": {
+        "title": "LinterTests",
+        "description": "Use this swagger to test the linter to detect response types with arrays as possible pageable operations",
+        "version": "2016-10-10"
+    },
+    "host": "management.azure.com",
+    "paths": {
+        "/plants": {
+            "get": {
+                "description": "Get a list of plants.",
+                "operationId": "Plants_List",
+                "parameters": [],
+                "responses": {
+                    "200": {
+                        "description": "OK.",
+                        "schema": {
+                            "$ref": "#/definitions/PlantsList"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "PlantsList": {
+            "type": "object",
+            "description": "Response to a Pageable operation. This one lists plants",
+            "properties": {
+                "value": {
+                    "type": "array",
+                    "description": "List of plants",
+                    "items": {
+                        "$ref": "#/definitions/Plant"
+                    }
+                },
+                "nextLink": {
+                    "type": "string",
+                    "description": "Link to next page of results"
+                }
+            }
+        },
+        "Plant": {
+            "type": "object",
+            "description": "A plant",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "The plant's name"
+                },
+                "edible": {
+                    "type": "boolean",
+                    "description": "Is the plant edible?"
+                }
+            }
+        }
+    },
+    "parameters": {}
+}