api-quality-spectral-ruleset 1.2.0 → 1.3.0-beta.1

package/apq-spectral.yaml

@@ -23,6 +23,7 @@ functions:
   - apq-binary-format-check
   - apq-paged-response-check
   - apq-status-endpoint-check
+  - apq-validate-structure
 extends:
   - spectral:asyncapi
   - spectral:oas
@@ -436,8 +437,8 @@ rules:
         status-endpoint: "/status"
         method: "get"
   apiq:OAR031:
-    description: The examples can help developers to understand the response data structure and representation."
-    message: "OAR031: Examples - Parameters, Request Body and Responses must have an examples defined."
+    description: "The examples can help developers to understand the response data structure and representation."
+    message: "{{error}}"
     severity: error
     given:
       - $.paths.*.*.parameters.*
@@ -576,6 +577,17 @@ rules:
       function: pattern
       functionOptions:
         match: "^(/api-[^/]+/v[0-9]+|https?:\\/\\/[^/]+\\/api-[^/]+\\/v[0-9]+)$"
+  apiq:OAR043:
+    description: "OpenAPI definition contains structural errors that would be detected by a strict parser or validator."
+    message: "{{error}}"
+    severity: error
+    given:
+      - $.paths.*.*.parameters.*.in
+      - $.components.parameters.*.in
+      - $.paths.*.*.parameters.*.schema.type
+      - $.components.parameters.*.schema.type
+    then:
+      function: apq-validate-structure
   apiq:OAR044:
     description: "Declared media type should conform to RFC6838 and RFC7231."
     message: "OAR044: Declared media type range should conform to RFC7231."

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

@@ -6,61 +6,87 @@
 module.exports = (given, options, context) => {
   if (!given || typeof given !== 'object') return [];
 
-  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));
-    }
+  const issues = [];
+  const nodePath = context.path || [];
 
-    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[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);
-    }
-
-    if (schema.allOf && Array.isArray(schema.allOf)) {
-      return schema.allOf.some(subSchema => checkSchema(subSchema));
-    }
-
-    if (schema.oneOf && Array.isArray(schema.oneOf)) {
-      return schema.oneOf.some(subSchema => checkSchema(subSchema));
+    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;
+  };
 
-    if (schema.anyOf && Array.isArray(schema.anyOf)) {
-      return schema.anyOf.some(subSchema => checkSchema(subSchema));
+  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;
   };
 
   if (!hasExample(given)) {
-    return [
-      {
-        message: context.rule.message
-      },
-    ];
+    issues.push({ message: context.rule.message });
+  }
+
+  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']);
+        }
+      }
+    } else if (given.schema) {
+      collectPropertyIssues(given.schema, ['schema']);
+    }
   }
 
-  return [];
-};
+  return issues;
+};

package/functions/apq-path-depth.js

@@ -10,6 +10,7 @@ module.exports = (targetVal, options, context) => {
   const segments = targetVal
     .split('/')
     .filter(Boolean)
+    .filter(segment => !segment.startsWith('{') && !segment.endsWith('}'))
     .filter(segment => !ignore.includes(segment))
 
   if (segments.length > maxDepth) {

package/functions/apq-validate-structure.js

@@ -0,0 +1,32 @@
+/**
+ * @param {string} given  - The field value
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  if (given === null || given === undefined) return [];
+
+  const VALID_IN_VALUES = ['query', 'header', 'path', 'cookie', 'body', 'formData'];
+  const VALID_SCHEMA_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object', 'null'];
+
+  const nodePath = context.path || [];
+  const fieldName = nodePath[nodePath.length - 1];
+
+  if (fieldName === 'in') {
+    if (!VALID_IN_VALUES.includes(String(given))) {
+      return [{
+        message: `in: Expected one of [${VALID_IN_VALUES.map(v => `"${v}"`).join(', ')}]`,
+      }];
+    }
+  }
+
+  if (fieldName === 'type') {
+    if (!VALID_SCHEMA_TYPES.includes(String(given))) {
+      return [{
+        message: `type: Expected one of [${VALID_SCHEMA_TYPES.map(v => `"${v}"`).join(', ')}]`,
+      }];
+    }
+  }
+
+  return [];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-quality-spectral-ruleset",
-  "version": "1.2.0",
+  "version": "1.3.0-beta.1",
   "description": "Spectral ruleset by API Quality",
   "main": "apq-spectral.yaml",
   "files": [
@@ -11,7 +11,11 @@
     "test": "jest --coverage --detectOpenHandles --no-cache --forceExit",
     "make-badges": "coverage-badges"
   },
-  "keywords": ["spectral", "linter", "openapi"],
+  "keywords": [
+    "spectral",
+    "linter",
+    "openapi"
+  ],
   "author": {
     "name": "APIQuality"
   },