api-quality-spectral-ruleset 1.1.0 → 1.1.2

package/apq-spectral.yaml

@@ -10,8 +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
@@ -109,19 +112,21 @@ 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)."
+    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."
@@ -147,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."
@@ -168,24 +176,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."
@@ -261,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."
@@ -285,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."
@@ -358,14 +409,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."
@@ -820,16 +871,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."
@@ -966,9 +1033,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."
@@ -1034,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-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-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.0",
+  "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;
-};