api-quality-spectral-ruleset 1.0.0 → 1.1.1

package/apq-spectral.yaml

@@ -7,6 +7,12 @@ functions:
   - apq-resources-by-verb
   - apq-at-most-one-body-parameter
   - apq-standard-response-codes
+  - apq-response-headers
+  - apq-require-response-on-path-params
+  - apq-required-fields-exist
+  - apq-security-check
+  - apq-custom-field
+  - apq-check-examples-coverage
 extends:
   - spectral:asyncapi
   - spectral:oas
@@ -111,12 +117,15 @@ rules:
   apiq:OAR011:
     description: "URLs should follow the specified naming convention: all literal path segments must be in kebab-case."
     message: "OAR011: The resource names with more than two words must be compliant with the standard naming convention (kebab-case)."
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR011.md"
     severity: error
-    given: "$.paths[*]~"
+    given:
+      - "$.paths[*]~"
+      - "$.servers[*].url"
     then:
       function: pattern
       functionOptions:
-        match: "^(\/|[a-z0-9-]+|{[a-zA-Z0-9_|-]+})+$"
+        match: "^(https?:\\/\\/[^\\/]+)?(\\/(?:[a-z0-9]+(?:-[a-z0-9]+)*|\\{[^}]+\\}))*\\/?$"
   apiq:OAR012:
     description: "Path params, query params, object names and property names should follow the configured naming convention. You can configure snake_case (default), kebab-case, camelCase or UpperCamelCase"
     message: "OAR012: Path params, query params, object names and property names must follow the configured naming convention."
@@ -163,24 +172,29 @@ rules:
     message: "OAR016: Numeric types must use a valid format for their type."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR016.md"
     severity: error
-    given:
-      - "$..[?(@.type == 'integer' && @.format)]"
-      - "$..[?(@.type == 'number' && @.format)]"
+    given: "$..[?(@.type=='number' || @.type=='integer')]"
     then:
       function: schema
       functionOptions:
         schema:
-          oneOf:
-            - properties:
-                type:
-                  const: integer
-                format:
-                  enum: [int32, int64]
-            - properties:
-                type:
-                  const: number
-                format:
-                  enum: [float, double]
+          required: [format]
+          allOf:
+            - if:
+                properties:
+                  type:
+                    const: integer
+              then:
+                properties:
+                  format:
+                    enum: [int32, int64]
+            - if:
+                properties:
+                  type:
+                    const: number
+              then:
+                properties:
+                  format:
+                    enum: [float, double]
   apiq:OAR017:
     description: "Resource path should alternate static and parametrized parts."
     message: "OAR017: Resource path should alternate static and parametrized parts."
@@ -353,14 +367,14 @@ rules:
       function: truthy
   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."
+    message: "OAR031: Examples - Parameters, Request Body and Responses must have an examples defined."
     severity: error
     given:
       - $.paths.*.*.parameters.*
-      - $.paths.*.*[responses,requestBody]..content.*
+      - $.paths.*.*.requestBody
+      - $.paths.*.*.responses[?(@property !== "204")]
     then:
-      field: examples
-      function: truthy
+      function: apq-check-examples-coverage
   apiq:OAR032:
     description: "Ambiguous path parts not encouraged."
     message: "OAR032: When reading a URL, it must be possible to interpret which resources it is referring to in a concrete way. Ambiguous names in resources must be avoided."
@@ -481,6 +495,17 @@ rules:
     then:
       field: "x-aut-type"
       function: truthy
+  apiq:OAR042:
+    description: "Base path must be compliant with the standard."
+    message: "OAR042: Base path must follow the '/api-<name>/v<version>' standard."
+    severity: "error"
+    given:
+      - "$.basePath"
+      - "$.servers[*].url"
+    then:
+      function: pattern
+      functionOptions:
+        match: "^(/api-[^/]+/v[0-9]+|https?:\\/\\/[^/]+\\/api-[^/]+\\/v[0-9]+)$"
   apiq:OAR044:
     description: "Declared media type should conform to RFC6838 and RFC7231."
     message: "OAR044: Declared media type range should conform to RFC7231."
@@ -590,6 +615,20 @@ rules:
     then:
       field: format
       function: truthy
+  apiq:OAR053:
+    description: "There are mandatory response headers and others that are not allowed."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR053.md"
+    severity: error
+    given: "$.paths[*][*].responses[*]"
+    then:
+      - function: apq-response-headers
+        functionOptions:
+          mandatory-headers: "x-trace-id,x-request-id"
+          allowed-headers: "idcorrelacion,x-correlacionid,x-global-trasaction-id,x-power-by,x-trace-id,x-request-id"
+          included-response-codes: "*"
+          excluded-response-codes: "204"
+          path-exclusions: "/status,/prueba"
   apiq:OAR054:
     description: "Ensure the host matches the specified format"
     message: "OAR054: Hostname must be a subdomain of the organization's domain name."
@@ -790,16 +829,32 @@ rules:
                 - required: ["enum"]
   apiq:OAR076:
     description: "Schema should use well-defined type and format."
-    message: "OAR076: Invalid combination: type '{{value.type}}' with format '{{value.format}}'"
-    severity: "error"
-    given: "$..[?(@.type=='number')]"
+    message: "OAR076: Schema should use well-defined type and format."
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR076.md"
+    severity: error
+    given: "$..[?(@.type=='number' || @.type=='integer')]"
     then:
-      field: format
-      function: enumeration
+      function: schema
       functionOptions:
-        values:
-          - float
-          - double
+        schema:
+          required: [format]
+          allOf:
+            - if:
+                properties:
+                  type:
+                    const: integer
+              then:
+                properties:
+                  format:
+                    enum: [int32, int64]
+            - if:
+                properties:
+                  type:
+                    const: number
+              then:
+                properties:
+                  format:
+                    enum: [float, double]
   apiq:OAR077:
     description: "All parameters in query must be snake_case."
     message: "OAR077: All parameters in query must be snake_case."
@@ -812,20 +867,22 @@ rules:
         match: ^\$?_?[a-z]+(_[a-z]+)*$
   apiq:OAR078:
     description: "All API methods must have security defined."
-    message: "OAR078: The operation '{{property}}' must have security defined."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR078.md"
     severity: error
-    given: "$.paths[*][get,post,put,patch,delete]"
+    given: "$"
     then:
-      field: "security"
-      function: truthy
+      function: apq-security-check
   apiq:OAR079:
     description: "Operations with path parameters should include a 404 Not Found response."
     message: "OAR079: Path parameter present, but missing 404 Not Found response."
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR079.md"
     severity: "warn"
-    given: "$.paths[*][*]"
+    given: "$.paths[*][get,post,put,patch,delete]"
     then:
-      field: responses.404
-      function: truthy
+      function: apq-require-response-on-path-params
+      functionOptions:
+        response: "404"
   apiq:OAR080:
     description: "The security scheme must be among those allowed by the organization and must be complete."
     message: "OAR080: The security scheme '{{property}}' must be among those allowed by the organization and must be complete."
@@ -934,9 +991,12 @@ rules:
   apiq:OAR091:
     description: "Parameters must contain only $ref references."
     message: "OAR091: Parameters must contain only $ref references."
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR091.md"
     severity: error
-    given: "$.paths[*][get,post,put,patch,delete].parameters[*].$ref"
+    resolved: false
+    given: "$.paths[*][get,post,put,patch,delete].parameters[*]"
     then:
+      field: $ref
       function: truthy
   apiq:OAR092:
     description: "RequestBody must contain a $ref."
@@ -1101,19 +1161,35 @@ rules:
     then:
       field: "contact"
       function: truthy
+  apiq:OAR113:
+    description: "Field or extension must be at the assigned location"
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR113.md"
+    severity: warn
+    given: "$"
+    then:
+      function: apq-custom-field
+      functionOptions:
+        fieldName: "x-custom-example"
+        fieldLocation: "path,operation_get,response_200"
   apiq:OAR114:
-    description: There are mandatory response headers and others that are not allowed.
-    message: "OAR114: Missing mandatory response x-api-key and x-trace-id headers, or forbidden headers are present."
-    documentationUrl: https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR114.md
-    severity: error
-    given: "$.paths[*][*].responses[*].headers"
+    description: "There are mandatory response headers and others that are not allowed."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR114.md"
+    severity: "error"
+    given: "$.paths[*][*].responses[*]"
     then:
-      - function: schema
+      - function: apq-response-headers
         functionOptions:
-          schema:
-            type: object
-            required:
-              - x-api-key
-              - x-trace-id
-            propertyNames:
-              pattern: "^(x-api-key|x-trace-id|traceId|dateTime)$"
+          mandatory-headers: "x-api-key,x-trace-id"
+          allowed-headers: "x-api-key,x-trace-id,traceId,dateTime"
+  apiq:OAR115:
+    description: "All fields listed in the required array must be defined in the schema properties."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR115.md"
+    severity: warn
+    given:
+      - "$.components.schemas[*]"
+      - "$.definitions[*]"
+    then:
+      function: apq-required-fields-exist

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

@@ -0,0 +1,54 @@
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+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));
+    }
+
+    if (node.schema) {
+      return checkSchema(node.schema);
+    }
+
+    if (node.properties || node.items || node.type) {
+      return checkSchema(node);
+    }
+
+    return false;
+  };
+
+  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);
+    }
+
+    return false;
+  };
+
+  if (!hasExample(given)) {
+    return [
+      {
+        message: context.rule.message
+      },
+    ];
+  }
+
+  return [];
+};

package/functions/apq-custom-field.js

@@ -0,0 +1,70 @@
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {string} options.fieldName
+ * @param {string} options.fieldLocation
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const { fieldName, fieldLocation } = options || {};
+  const ruleCode = context.rule.name.split(':').pop();
+
+  if (!given || !fieldName || !fieldLocation) return [];
+
+  const locations = fieldLocation.split(',').map(l => l.trim());
+  const results = [];
+
+  const hasField = node =>
+    node && typeof node === 'object' && Object.prototype.hasOwnProperty.call(node, fieldName);
+
+  const addError = path =>
+    results.push({
+      message: `${ruleCode}: Field or extension ${fieldName} must be at the assigned location`,
+      path,
+    });
+
+  if (hasField(given)) {
+    return [];
+  }
+
+  const rootLocations = ['path', 'components'];
+
+  const missingRoot = rootLocations.find(
+    loc => locations.includes(loc) && !given[loc === 'path' ? 'paths' : loc]
+  );
+
+  if (missingRoot) {
+    return [
+      {
+        message: `${ruleCode}: The location ${missingRoot} is not present.`,
+        path: [],
+      },
+    ];
+  }
+
+  const opLoc = locations.find(l => l.startsWith('operation_'));
+  const respLoc = locations.find(l => l.startsWith('response_'));
+
+  const verb = opLoc?.split('_')[1];
+  const status = respLoc?.split('_')[1];
+
+  Object.entries(given.paths || {}).forEach(([pathKey, pathItem]) => {
+    if (hasField(pathItem)) return;
+
+    if (!verb || !pathItem[verb]) return;
+
+    const operation = pathItem[verb];
+
+    if (hasField(operation)) return;
+
+    if (!operation.responses || !operation.responses[status]) return;
+
+    const response = operation.responses[status];
+
+    if (!hasField(response)) {
+      addError(['paths', pathKey, verb, 'responses', status]);
+    }
+  });
+
+  return results;
+};

package/functions/apq-require-response-on-path-params.js

@@ -0,0 +1,62 @@
+/**
+ * Requires one or more HTTP response codes when path parameters are present.
+ *
+ * @param {object} given
+ * @param {object} options
+ * @param {string} options.response Comma-separated HTTP status codes (e.g. "400,404,200")
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  if (!given || typeof given !== 'object') {
+    return [];
+  }
+
+  const ruleCode = context.rule?.name?.split(':').pop();
+  const responseOpt = options?.response;
+
+  if (typeof responseOpt !== 'string') {
+    throw new TypeError(`${ruleCode}: "response" option must be a comma-separated string of HTTP status codes`);
+  }
+
+  const requiredResponses = responseOpt
+    .split(',')
+    .map(r => r.trim())
+    .filter(r => /^\d{3}$/.test(r));
+
+  if (requiredResponses.length === 0) {
+    throw new Error(`${ruleCode}: No valid HTTP status codes found in "response" option`);
+  }
+
+  const pathItemKeyIndex = context.path?.length - 2;
+  const pathItem = typeof pathItemKeyIndex === 'number'
+    ? context.path?.[pathItemKeyIndex]
+    : null;
+
+  const pathParams = (pathItem?.parameters || []).filter(
+    p => p?.in === 'path'
+  );
+
+  const operationParams = (given.parameters || []).filter(
+    p => p?.in === 'path'
+  );
+
+  if (pathParams.length === 0 && operationParams.length === 0) {
+    return [];
+  }
+
+  const responses = given?.responses || {};
+
+  const hasRequiredResponse = requiredResponses.some(
+    code => responses[code]
+  );
+
+  if (!hasRequiredResponse) {
+    return [
+      {
+        message: context.rule.message,
+      }
+    ];
+  }
+
+  return [];
+};

package/functions/apq-required-fields-exist.js

@@ -0,0 +1,27 @@
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const results = [];
+
+  if (!given || given.type !== 'object') return results;
+
+  const { required, properties } = given;
+  if (!Array.isArray(required)) return results;
+
+  const propertyNames = new Set(Object.keys(properties || {}));
+  const ruleCode = context.rule.name.split(':').pop();
+
+  required.forEach((field, index) => {
+    if (!propertyNames.has(field)) {
+      results.push({
+        message: `${ruleCode}: This value does not exist, '${field}' must be defined in the schema properties.`,
+        path: [...context.path, 'required', index]
+      });
+    }
+  });
+
+  return results;
+};

package/functions/apq-response-headers.js

@@ -0,0 +1,94 @@
+module.exports = (responseNode, options = {}, context) => {
+  if (!responseNode || typeof responseNode !== 'object') {
+    return [];
+  }
+
+  const results = [];
+
+  const {
+    'mandatory-headers': mandatoryHeadersOpt = '',
+    'allowed-headers': allowedHeadersOpt = '',
+    'included-response-codes': includedCodesOpt = '*',
+    'excluded-response-codes': excludedCodesOpt = '',
+    'path-exclusions': pathExclusionsOpt = '',
+  } = options;
+
+  const mandatoryHeaders = mandatoryHeadersOpt
+    .split(',')
+    .map(h => h.toLowerCase().trim())
+    .filter(Boolean);
+
+  const allowedHeaders = allowedHeadersOpt
+    .split(',')
+    .map(h => h.toLowerCase().trim())
+    .filter(Boolean);
+
+  const includedCodes = includedCodesOpt
+    .split(',')
+    .map(c => c.trim())
+    .filter(Boolean);
+
+  const excludedCodes = excludedCodesOpt
+    .split(',')
+    .map(c => c.trim())
+    .filter(Boolean);
+
+  const pathExclusions = pathExclusionsOpt
+    .split(',')
+    .map(p => p.trim())
+    .filter(Boolean);
+
+  const path = context.path?.find(p => typeof p === 'string' && p.startsWith('/'));
+  const responseCode = context.path?.[context.path.length - 1];
+
+  if (path && pathExclusions.includes(path)) {
+    return [];
+  }
+
+  if (excludedCodes.includes(String(responseCode))) {
+    return [];
+  }
+
+  if (!includedCodes.includes('*') && !includedCodes.includes(String(responseCode))) {
+    return [];
+  }
+
+  let headers = responseNode.headers;
+
+  if (!headers && responseNode.$ref && context.document?.resolved) {
+    try {
+      const ref = responseNode.$ref.replace(/^#\//, '').split('/');
+      let resolved = context.document.resolved;
+      for (const part of ref) {
+        resolved = resolved?.[part];
+      }
+      headers = resolved?.headers;
+    } catch (_) {
+    }
+  }
+
+  const headerNames = headers && typeof headers === 'object'
+    ? Object.keys(headers).map(h => h.toLowerCase().trim())
+    : [];
+  const ruleCode = context.rule.name.split(':').pop();
+
+  if (mandatoryHeaders.length > 0) {
+    const missing = mandatoryHeaders.filter(h => !headerNames.includes(h));
+    if (missing.length > 0) {
+      results.push({
+        message: `${ruleCode}: Headers [${missing.join(', ')}] are required`,
+      });
+    }
+  }
+
+  if (allowedHeaders.length > 0 && headerNames.length > 0) {
+    const forbidden = headerNames.filter(h => !allowedHeaders.includes(h));
+    if (forbidden.length > 0) {
+      results.push({
+        message: `${ruleCode}: Header not allowed`,
+      });
+    }
+  }
+
+  return results;
+};

package/functions/apq-security-check.js

@@ -0,0 +1,35 @@
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  if (!given) return [];
+
+  const results = [];
+  const ruleCode = context.rule.name.split(':').pop();
+
+  const globalSecurity = given.security ?? given.swagger?.security;
+  if (globalSecurity) {
+    return results;
+  }
+
+  const methods = ['get', 'post', 'put', 'patch', 'delete'];
+
+  const pathsObj = given.paths || {};
+  for (const [pathName, pathItem] of Object.entries(pathsObj)) {
+    for (const method of methods) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+
+      if (!operation.security || operation.security.length === 0) {
+        results.push({
+          message: `${ruleCode}: The operation '${method} ${pathName}' must have security defined.`,
+          path: ['paths', pathName, method, 'security']
+        });
+      }
+    }
+  }
+
+  return results;
+};

package/functions/apq-standard-response-codes.js

@@ -1,9 +1,14 @@
-module.exports = function apqStandardResponseCodes(targetVal, options, context) {
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = function apqStandardResponseCodes(given, options, context) {
   const results = [];
 
-  if (!targetVal || !context?.path) return results;
+  if (!given || !context?.path) return results;
 
-  const responses = targetVal.responses;
+  const responses = given.responses;
   if (!responses || typeof responses !== 'object') return results;
 
   const definedCodes = Object.keys(responses);
@@ -17,15 +22,15 @@ module.exports = function apqStandardResponseCodes(targetVal, options, context)
 
   const exclusions = options?.['resources-exclusions'] || [];
   if (exclusions.some(ex => {
-      const [exVerb, exPath] = ex.split(':');
-      return exVerb.toLowerCase() === verb.toLowerCase() && new RegExp(`^${exPath}$`).test(resourcePath);
-    })) return results;
+    const [exVerb, exPath] = ex.split(':');
+    return exVerb.toLowerCase() === verb.toLowerCase() && new RegExp(`^${exPath}$`).test(resourcePath);
+  })) return results;
 
   const rulesConfig = options?.['required-codes-by-resources-paths'];
   if (!rulesConfig) return results;
 
   const rules = rulesConfig
-    .split(/[\n;]/) 
+    .split(/[\n;]/)
     .map(r => r.trim())
     .filter(Boolean)
     .map(rule => {
@@ -49,19 +54,19 @@ module.exports = function apqStandardResponseCodes(targetVal, options, context)
 
   if (!matchedRule) return results;
 
-matchedRule.requiredCodes.forEach(ruleCode => {
+  matchedRule.requiredCodes.forEach(respCode => {
     let missing = false;
     let msg = "";
 
-    if (ruleCode.includes('|')) {
-      const alternatives = ruleCode.split('|');
+    if (respCode.includes('|')) {
+      const alternatives = respCode.split('|');
       if (!alternatives.some(c => definedCodes.includes(c))) {
         missing = true;
         msg = `OAR039: Response code ${alternatives.join(' or ')} must be defined.`;
       }
-    } else if (!definedCodes.includes(ruleCode)) {
+    } else if (!definedCodes.includes(respCode)) {
       missing = true;
-      msg = `OAR039: Response code ${ruleCode} must be defined.`;
+      msg = `OAR039: Response code ${respCode} must be defined.`;
     }
 
     if (missing) {

package/package.json

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