api-quality-spectral-ruleset 1.4.1-beta.2 → 1.4.1-beta.4

package/apq-spectral.yaml

@@ -295,7 +295,9 @@ rules:
     then:
       function: apq-collection-query-param-required
       functionOptions:
-        parameter-name: "$expand"
+        parameterName: "$expand"
+        paths: "/me,/health,/ping,/status"
+        pathValidationStrategy: "/exclude"
   apiq:OAR021:
     description: "$exclude must be defined as a query parameter in collection operations (excluding detail endpoints and health checks)."
     message: "{{error}}"
@@ -304,34 +306,21 @@ rules:
     then:
       function: apq-collection-query-param-required
       functionOptions:
-        parameter-name: "$exclude"
+        parameterName: "$exclude"
+        paths: "/me,/health,/ping,/status"
+        pathValidationStrategy: "/exclude"
   apiq:OAR022:
-    description: "$orderby must be defined as a query parameter in all operations."
-    message: "OAR022: $orderby must be defined as a query parameter in this operation."
+    description: "$orderby must be defined as a query parameter in the collection GET operations selected by the configured paths."
+    message: "{{error}}"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR022.md"
     severity: warn
-    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/))].get"
+    given: "$.paths"
     then:
-      function: schema
+      function: apq-collection-query-param-required
       functionOptions:
-        schema:
-          if:
-            properties:
-              responses:
-                required: ["206"]
-          then:
-            required: ["parameters"]
-            properties:
-              parameters:
-                type: array
-                contains:
-                  type: object
-                  properties:
-                    name:
-                      const: "$orderby"
-                    in:
-                      const: query
-                  required: [name, in]
+        parameterName: "$orderby"
+        paths: "/examples"
+        pathValidationStrategy: "/include"
   apiq:OAR023:
     description: "$total must be defined as a query parameter in all collection operations (excluding detail endpoints and health checks)."
     message: "OAR023: $total must be defined as a query parameter in this operation."
@@ -349,38 +338,17 @@ rules:
       field: "$[?(@.name == '$start' && @.in == 'query')]"
       function: truthy
   apiq:OAR025:
-    description: "$limit must be defined as a query parameter in all collection operations (excluding detail endpoints and health checks)."
-    message: "OAR025: $limit must be defined as a query parameter in this operation."
+    description: "$limit must be defined as a query parameter in the collection GET operations selected by the configured paths."
+    message: "{{error}}"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR025.md"
     severity: error
-    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get"
+    given: "$.paths"
     then:
-      function: schema
+      function: apq-collection-query-param-required
       functionOptions:
-        schema:
-          if:
-            properties:
-              responses:
-                required: ["206"]
-          then:
-            required: ["parameters"]
-            properties:
-              parameters:
-                type: array
-                contains:
-                  type: object
-                  properties:
-                    name:
-                      const: "$limit"
-                    in:
-                      const: query
-                    schema:
-                      type: object
-                      properties:
-                        type:
-                          const: integer
-                      required: [type]
-                  required: [name, in, schema]
+        parameterName: "$limit"
+        paths: "/examples"
+        pathValidationStrategy: "/include"
   apiq:OAR026:
     description: "The $total parameter default value should be false."
     message: "OAR026: The $total parameter default value should be false."

package/functions/apq-collection-query-param-required.js

@@ -6,13 +6,17 @@ const STRATEGY_EXCLUDE = 'Exclude';
 
 const escapeRegExp = (segment) => segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
-
 const parsePathPatterns = (paths) => paths
-  .split(/[\n;]/)
+  .split(/[\n;,]/)
   .map((p) => p.trim())
   .filter(Boolean)
   .map((segment) => new RegExp(`${escapeRegExp(segment)}(/|$)`));
 
+const normalizeStrategy = (value) => {
+  const normalized = String(value == null ? '' : value).trim().replace(/^\//, '').toLowerCase();
+  return normalized === 'include' ? STRATEGY_INCLUDE : STRATEGY_EXCLUDE;
+};
+
 const shouldIncludePath = (path, patterns, strategy) => {
   const matchesList = patterns.some((regex) => regex.test(path));
   return strategy === STRATEGY_INCLUDE ? matchesList : !matchesList;
@@ -21,6 +25,15 @@ const shouldIncludePath = (path, patterns, strategy) => {
 const hasQueryParameter = (parameters, parameterName) => Array.isArray(parameters)
   && parameters.some((p) => p && !p.$ref && p.name === parameterName && p.in === 'query');
 
+const PAGINATED_RESPONSE_CODE = '206';
+const PAGINATED_RULE_CODES = ['OAR022', 'OAR025'];
+
+const hasResponseCode = (operation, code) => {
+  const responses = operation && operation.responses;
+  return !!responses && typeof responses === 'object'
+    && Object.prototype.hasOwnProperty.call(responses, code);
+};
+
 /**
  * @param {object} given
  * @param {object} options
@@ -31,21 +44,21 @@ module.exports = (given, options = {}, context) => {
 
   const ruleCode = context && context.rule && context.rule.name ? context.rule.name.split(':').pop() : 'apq-collection-query-param-required';
 
-  const parameterName = options['parameter-name'];
+  const parameterName = options.parameterName != null ? options.parameterName : options['parameter-name'];
   if (!parameterName) {
     return [{
-      message: `${ruleCode}: "parameter-name" functionOption is required.`,
+      message: `${ruleCode}: "parameterName" functionOption is required.`,
       path: context.path,
     }];
   }
 
-  const strategy = options.pathValidationStrategy === STRATEGY_INCLUDE
-    ? STRATEGY_INCLUDE
-    : STRATEGY_EXCLUDE;
+  const strategy = normalizeStrategy(options.pathValidationStrategy);
 
   const rawPaths = typeof options.paths === 'string' ? options.paths : DEFAULT_PATHS;
   const patterns = parsePathPatterns(rawPaths);
 
+  const requiresPaginated = PAGINATED_RULE_CODES.includes(ruleCode);
+
   const results = [];
 
   Object.entries(given).forEach(([path, pathItem]) => {
@@ -56,6 +69,7 @@ module.exports = (given, options = {}, context) => {
 
     if (PATH_PARAM_SUFFIX_REGEX.test(path)) return;
     if (!shouldIncludePath(path, patterns, strategy)) return;
+    if (requiresPaginated && !hasResponseCode(getOperation, PAGINATED_RESPONSE_CODE)) return;
 
     if (!hasQueryParameter(getOperation.parameters, parameterName)) {
       results.push({

package/functions/apq-security-required-response.js

@@ -20,10 +20,13 @@ module.exports = (given, options, context) => {
     .map((code) => String(code).trim())
     .filter(Boolean);
 
+  const operationSecurityDefined = Array.isArray(given.security);
+  if (operationSecurityDefined && given.security.length === 0) {
+    return results;
+  }
+
   // Check if this operation has security defined
-  const operationHasSecurity = given.security &&
-    Array.isArray(given.security) &&
-    given.security.length > 0;
+  const operationHasSecurity = operationSecurityDefined && given.security.length > 0;
 
   // Check if there's global security in the document
   let globalHasSecurity = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-quality-spectral-ruleset",
-  "version": "1.4.1-beta.2",
+  "version": "1.4.1-beta.4",
   "description": "Spectral ruleset by API Quality",
   "main": "apq-spectral.yaml",
   "files": [