api-quality-spectral-ruleset 1.1.1 → 1.1.2

package/apq-spectral.yaml

@@ -10,9 +10,11 @@ functions:
   - apq-response-headers
   - apq-require-response-on-path-params
   - apq-required-fields-exist
+  - apq-response-media-type
   - apq-security-check
   - apq-custom-field
   - apq-check-examples-coverage
+  - apq-path-depth
 extends:
   - spectral:asyncapi
   - spectral:oas
@@ -110,10 +112,9 @@ rules:
     description: "Default response media type should be defined for responses."
     message: "OAR010: Default response media type is mandatory."
     severity: warn
-    given: "$.paths[*][get,post,put,patch,delete].responses[*]"
+    given: "$.paths[*][get,post,put,patch,delete]"
     then:
-      field: "content['application/json']"
-      function: truthy
+      function: apq-response-media-type
   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)."
@@ -151,13 +152,16 @@ rules:
       function: truthy
   apiq:OAR014:
     description: "Resources depth level should be below the non-suggested range."
-    message:     "OAR014: The number of parts of the path must be less than 4."
-    severity:   warn
-    given:      "$.paths.*~"             
+    message: "OAR014: The number of parts of the path must be less than 4."
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR014.md"
+    severity: warn
+    given: "$.paths.*~"
     then:
-      function: pattern                     
+      function: apq-path-depth
       functionOptions:
-        notMatch: "^(?:\\/[^\\/]+){4,}"        
+        maxDepth: 3
+        ignoreSegments:
+          - me
   apiq:OAR015:
     description: "Resources depth level should be smaller than 5."
     message: "OAR015: Path exceeds the maximum allowed depth level of 5."
@@ -270,11 +274,30 @@ rules:
   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."
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR022.md"
     severity: warn
-    given: "$.paths[*].get.parameters"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/))].get"
     then:
-      field: "$[?(@.name == '$orderby' && @.in == 'query')]"
-      function: truthy
+      function: schema
+      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]
   apiq:OAR023:
     description: "$total must be defined as a query parameter in all operations."
     message: "OAR023: $total must be defined as a query parameter in this operation."
@@ -294,11 +317,30 @@ rules:
   apiq:OAR025:
     description: "$limit must be defined as a query parameter in all operations."
     message: "OAR025: $limit must be defined as a query parameter in this operation."
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR025.md"
     severity: error
-    given: "$.paths[*].get.parameters"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/))].get"
     then:
-      field: "$[?(@.name == '$limit' && @.in == 'query')]"
-      function: truthy
+      function: schema
+      functionOptions:
+        schema:
+          if:
+            properties:
+              responses:
+                required: ["206"]
+          then:
+            required: ["parameters"]
+            properties:
+              parameters:
+                type: array
+                contains:
+                  type: object
+                  properties:
+                    name:
+                      const: "$limit"
+                    in:
+                      const: query
+                  required: [name, in]
   apiq:OAR026:
     description: "The $total parameter default value should be false."
     message: "OAR026: The $total parameter default value should be false."
@@ -1062,11 +1104,13 @@ rules:
     description: "Last path part must be the API version, indicated with the prefix 'v' and the version number as integer."
     message: "OAR100: Last path part must be the API version, indicated with the prefix 'v' and the version number as integer."
     severity: "error"
-    given: "$.servers[*].url"
+    given:
+      - "$.servers[*].url"
+      - "$.basePath"
     then:
       function: pattern
       functionOptions:
-        match: "^https?://[^/]+/.*/v[0-9]+$"
+        match: "^(https?://[^/]+)?(?:/[^/]+)*/v[0-9]+$"
   apiq:OAR101:
     description: "The first part of the path should be one of the allowed paths (e.g., '/hello')."
     message: "OAR101: The first part of the path should be one of the allowed paths."

package/functions/apq-path-depth.js

@@ -0,0 +1,20 @@
+/**
+ * @param {string} targetVal
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (targetVal, options, context) => {
+  const maxDepth = options.maxDepth ?? 3
+  const ignore = options.ignoreSegments ?? []
+
+  const segments = targetVal
+    .split('/')
+    .filter(Boolean)
+    .filter(segment => !ignore.includes(segment))
+
+  if (segments.length > maxDepth) {
+    return [
+      { message: context.rule.message }
+    ]
+  }
+}

package/functions/apq-response-media-type.js

@@ -0,0 +1,43 @@
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+
+const NO_BODY_CODES = new Set(['204']);
+
+module.exports = (given, options, context) => {
+  const errors = [];
+  if (!given) return errors;
+
+  const root = context.document.parserResult.data;
+
+  if (root.swagger) {
+    const produces = given.produces ?? root.produces;
+
+    if (!produces || !Array.isArray(produces) || !produces.includes('application/json')) {
+      errors.push({
+        message: context.rule.message,
+        path: [...context.path]
+      });
+    }
+
+    return errors;
+  }
+
+  const responses = given.responses;
+  if (!responses) return errors;
+
+  for (const [statusCode, response] of Object.entries(responses)) {
+    if (NO_BODY_CODES.has(statusCode)) continue;
+
+    if (!response?.content?.['application/json']) {
+      errors.push({
+        message: context.rule.message,
+        path: [...context.path, 'responses', statusCode]
+      });
+    }
+  }
+
+  return errors;
+};

package/package.json

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

package/functions/apq-default-value.js

@@ -1,23 +0,0 @@
-/**
- * @param {object} given
- * @param {object} options
- * @param {string} options.type
- * @param {string} options.match
- * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
- */
-module.exports = (given, options, context) => {
-    const errors = [];
-    if (!given) return errors;
-
-    if (!given.type || given.type.toString() !== options.type.toString()) {
-      errors.push({
-          message: context.rule.message,
-      });
-    } else if (!given.default || given.default.toString() !== options.match.toString()) {
-      errors.push({
-          message: context.rule.message,
-      });
-    }
-
-    return errors;
-}

package/functions/apq-naming-convention.js

@@ -1,21 +0,0 @@
-const { pattern } = require("@stoplight/spectral-functions");
-
-const patterns = {
-    kebabCase: /^(\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$/,
-    camelCase: /^[a-z]+([A-Z][a-z0-9]+)*$/,
-    snakeCase: /^[a-z]+(_[a-z0-9]+)*$/,
-    pascalCase: /^[A-Z]+([A-Z][a-z0-9]+)*$/
-};
-
-/**
- * @param {object} given
- * @param {object} options
- * @param {string} options.pattern
- * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
- */
-module.exports = (given, options, context) => {
-    const errors = [];
-    if (!given) return errors;
-
-    return pattern(given, { match: patterns[options.pattern] }, context);
-}

package/functions/apq-properties-schema-format.js

@@ -1,29 +0,0 @@
-// Check that format is valid for a schema type.
-
-/**
- * @param {object} given
- * @param {object} options
- * @param {Array<string>} options.formats
- * @param {Array<string>} options.properties
- * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
- */
-module.exports = function checkTypeAndFormat(given, options, context) {
-  if (given === null || typeof given !== "object") {
-    return [];
-  }
-
-  const errors = [];
-  const path = context.path || [];
-  const name = path.slice(-1)[0].toString();
-
-  if (options.properties.includes(name)) {
-    if (!given.format || !options.formats.includes(given.format)) {
-      errors.push({
-        message: context.rule.message,
-        path: [...path, name]
-      });
-    }
-  }
-
-  return errors;
-};