api-quality-spectral-ruleset 1.3.0-beta.5 → 1.3.0

package/apq-spectral.yaml

@@ -213,7 +213,7 @@ rules:
                     enum: [float, double, decimal]
   apiq:OAR017:
     description: "Resource path should alternate static and parametrized parts."
-    message: "OAR017: Resource path should alternate static and parametrized parts."
+    message: "OAR017: Resource path should alternate static and parametrized parts"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR017.md"
     severity: error
     given: "$.paths.*~"
@@ -829,7 +829,7 @@ rules:
     severity: "warn"
     given:
       - "$.paths.*.*[responses,requestBody]..content..schema..properties.*~"
-      - "$.paths.*.*.parameters[*].schema..properties.*~"
+      - "$.paths.*.*.parameters[?(@.in=='body')].schema..properties.*~"
       - "$.paths.*.*.responses[*].schema..properties.*~"
     then:
       function: pattern

package/functions/apq-check-examples-coverage.js

@@ -1,90 +1,70 @@
+const COMBINERS = ['allOf', 'oneOf', 'anyOf'];
+
+const checkSchema = (schema) => {
+  if (!schema || typeof schema !== 'object') return false;
+  if (schema.example !== undefined || schema.examples !== undefined) return true;
+  if (schema.properties) return Object.values(schema.properties).some(checkSchema);
+  if (schema.items) return checkSchema(schema.items);
+  return COMBINERS.some(c => Array.isArray(schema[c]) && schema[c].some(checkSchema));
+};
+
+const hasExample = (node) => {
+  if (!node || typeof node !== 'object') return false;
+  if (node.example !== undefined || node.examples !== undefined) return true;
+  if (node.content) return Object.values(node.content).some(hasExample);
+  if (node.schema) return checkSchema(node.schema);
+  return !!(node.properties || node.items || node.type) && checkSchema(node);
+};
+
+const collectPropertyIssues = (schema, issues) => {
+  if (!schema || typeof schema !== 'object' || schema.$ref) return;
+
+  if (schema.type === 'array') {
+    schema.items && collectPropertyIssues(schema.items, issues);
+    return;
+  }
+
+  if (schema.properties) {
+    for (const [propName, propSchema] of Object.entries(schema.properties)) {
+      if (!propSchema || typeof propSchema !== 'object' || propSchema.$ref) continue;
+      const propType = propSchema.type;
+      if (propType === 'object' || propType === 'array' || (!propType && propSchema.properties)) {
+        collectPropertyIssues(propSchema, issues);
+      } else if (propType !== undefined && propSchema.example === undefined && propSchema.examples === undefined) {
+        issues.push({ message: `OAR031: Property '${propName}' is missing an example.` });
+      }
+    }
+  }
+
+  COMBINERS.forEach(c => {
+    if (Array.isArray(schema[c])) schema[c].forEach(sub => collectPropertyIssues(sub, issues));
+  });
+};
+
 /**
  * @param {object} given
  * @param {object} options
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
-module.exports = (given, options, context) => {
+module.exports = function oar031ExamplesCoverage(given, options, context) {
   if (!given || typeof given !== 'object') return [];
 
   const issues = [];
   const nodePath = context.path || [];
-
-  const isParameter = nodePath.length >= 2 && nodePath[nodePath.length - 2] === 'parameters';
-
-  const checkSchema = (schema) => {
-    if (!schema || typeof schema !== 'object') return false;
-    if (schema.example !== undefined || schema.examples !== undefined) return true;
-    if (schema.properties && typeof schema.properties === 'object') {
-      return Object.values(schema.properties).some(prop => checkSchema(prop));
-    }
-    if (schema.items) return checkSchema(schema.items);
-    for (const combiner of ['allOf', 'oneOf', 'anyOf']) {
-      if (schema[combiner] && Array.isArray(schema[combiner])) {
-        if (schema[combiner].some(sub => checkSchema(sub))) return true;
-      }
-    }
-    return false;
-  };
-
-  const hasExample = (node) => {
-    if (!node || typeof node !== 'object') return false;
-    if (node.example !== undefined || node.examples !== undefined) return true;
-    if (node.content && typeof node.content === 'object') {
-      return Object.values(node.content).some(mediaType => hasExample(mediaType));
-    }
-    if (node.schema) return checkSchema(node.schema);
-    if (node.properties || node.items || node.type) return checkSchema(node);
-    return false;
-  };
+  const isParameter = nodePath.length >= 2 && nodePath.at(-2) === 'parameters';
+  const isBodyParam = isParameter && given.in === 'body';
 
   if (!hasExample(given)) {
     issues.push({ message: 'OAR031: Must have one or more examples defined' });
   }
 
-  if (!isParameter) {
-    const collectPropertyIssues = (schema, path) => {
-      if (!schema || typeof schema !== 'object' || schema.$ref) return;
-
-      if (schema.type === 'array' && schema.items) {
-        collectPropertyIssues(schema.items, [...path, 'items']);
-        return;
-      }
-
-      if (schema.properties && typeof schema.properties === 'object') {
-        for (const [propName, propSchema] of Object.entries(schema.properties)) {
-          if (!propSchema || typeof propSchema !== 'object' || propSchema.$ref) continue;
-
-          const propType = propSchema.type;
-
-          if (propType === 'object' || (!propType && propSchema.properties)) {
-            collectPropertyIssues(propSchema, [...path, 'properties', propName]);
-          } else if (propType === 'array') {
-            collectPropertyIssues(propSchema, [...path, 'properties', propName]);
-          } else {
-            if (propSchema.example === undefined && propSchema.examples === undefined) {
-              issues.push({ message: `OAR031: Property '${propName}' is missing an example.` });
-            }
-          }
-        }
-      }
-
-      for (const combiner of ['allOf', 'oneOf', 'anyOf']) {
-        if (schema[combiner] && Array.isArray(schema[combiner])) {
-          schema[combiner].forEach((sub, i) => {
-            collectPropertyIssues(sub, [...path, combiner, i]);
-          });
-        }
-      }
-    };
-
-    if (given.content && typeof given.content === 'object') {
-      for (const [mediaType, mediaTypeNode] of Object.entries(given.content)) {
-        if (mediaTypeNode && mediaTypeNode.schema) {
-          collectPropertyIssues(mediaTypeNode.schema, ['content', mediaType, 'schema']);
-        }
-      }
+  if (!isParameter || isBodyParam) {
+    if (given.content) {
+      Object.values(given.content).forEach(mt => {
+        if (mt?.schema) collectPropertyIssues(mt.schema, issues);
+      });
     } else if (given.schema) {
-      collectPropertyIssues(given.schema, ['schema']);
+      collectPropertyIssues(given.schema, issues);
     }
   }
 

package/package.json

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