API linting implementation guideline (#1)

artifacts/linting_rules/.spectral.yml

@@ -0,0 +1,212 @@
+extends: "spectral:oas"
+functions:
+  - camara-reserved-words
+  - camara-language-avoid-telco
+  - camara-security-no-secrets-in-path-or-query-parameters
+functionsDir: "./lint_function"
+rules:
+  #  Built-in OpenAPI Specification ruleset. Each rule then can be enabled individually.
+  #  The severity keyword is optional in rule definition and can be error, warn, info, hint, or off. The default value is warn.
+  contact-properties: false
+  duplicated-entry-in-enum: true
+  info-contact: true
+  info-description: true
+  info-license: true
+  license-url: true
+  no-$ref-siblings: error
+  no-eval-in-markdown: true
+  no-script-tags-in-markdown: true
+  openapi-tags: false
+  openapi-tags-alphabetical: false
+  openapi-tags-uniqueness: error
+  operation-description: true
+  operation-operationId: true
+  operation-operationId-unique: error
+  operation-operationId-valid-in-url: true
+  operation-parameters: true
+  operation-singular-tag: true
+  operation-success-response: true
+  operation-tags: true
+  operation-tag-defined: true
+  path-declarations-must-exist: true
+  path-keys-no-trailing-slash: true
+  path-not-include-query: true
+  path-params: error
+  tag-description: false
+  typed-enum: true
+  oas3-api-servers: true
+  oas3-examples-value-or-externalValue: true
+  oas3-operation-security-defined: true
+  oas3-parameter-description: false
+  oas3-schema: true
+  oas3-server-not-example.com: false
+  oas3-server-trailing-slash: true
+  oas3-unused-component: true
+  oas3-valid-media-example: true
+  oas3-valid-schema-example: true
+  oas3-server-variables: true
+
+  # Custom Rules Utilizing Spectral's Built-in Functions and JavaScript Implementations
+
+  camara-language-avoid-telco:
+    message: "{{error}}"
+    severity: hint
+    description: |
+      This rule checks for telco-specific terminology in your API definitions and suggests more inclusive terms.
+    given: "$..*.*"
+    then:
+      function: camara-language-avoid-telco
+    recommended: false  # Set to true/false to enable/disable this rule
+
+  camara-oas-version:
+    message: "OpenAPI Version Error: The OpenAPI specification must adhere to version 3.0.3."
+    severity: error
+    description: |
+      This rule validates the OpenAPI version in your specification and requires compliance with version 3.0.3.
+    given: "$"
+    then:
+      field: openapi
+      function: pattern
+      functionOptions:
+        match: 3.0.3
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-path-param-id:
+    message: "Path Parameter Naming Warning: Use 'resource_id' instead of just 'id' in path parameters."
+    severity: warn
+    description: |
+      This rule ensures consistent and descriptive naming for path parameters in your OpenAPI specification.
+      Please use 'resource_id' instead of just 'id' for your path parameters.
+    given: "$..parameters[?(@.in == 'path')]"
+    then:
+      field: name
+      function: pattern
+      functionOptions:
+        notMatch: \b(id|Id|ID|iD)\b
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-security-no-secrets-in-path-or-query-parameters:
+    message: "Sensitive data found in path: {{error}} Consider avoiding the use of Sesentive data "
+    severity: warn
+    description: |
+      This rule checks for sensitive data ('MSISDN' and 'IMSI') in API paths and suggests avoiding their use.
+    given:
+      - "$.paths"
+    then:
+      function: camara-security-no-secrets-in-path-or-query-parameters
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-http-methods:
+    description: "Ensure that all path URLs have valid HTTP methods (GET, PUT, POST, DELETE, PATCH, OPTIONS)."
+    message: "Invalid HTTP method for '{{path}}'. Must be one of get, put, post, delete, patch, options."
+    severity: error
+    given: $.paths[*][*]~
+    then:
+      function: pattern
+      functionOptions:
+        match: "^(get|put|post|delete|patch|options)$"
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-get-no-request-body:
+    message: There must be no request body for Get and DELETE
+    severity: error
+    given:
+      - "$.paths.*.get"
+      - "$.paths.*.delete"
+    then:
+      field: requestBody
+      function: falsy
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-reserved-words:
+    message: "Reserved words found {{error}} Consider avoiding the use of reserved word "
+    severity: warn
+    description: |
+      This rule checks Reserved words must not be used in the following parts of an API specification [Paths, Request Body properties, Component, Operation Id, Security Schema]
+    given:
+      - "$.paths"                              # Paths
+      - "$..parameters[*]"                     # Path or Query Parameter Names:
+      - "$..components.schemas.*.properties.*"   # Request and Response body parameter
+      - "$.paths.*."                           # Path and Operation Names:
+      - "$.components.securitySchemes"         # Security Schemes:
+      - "$.components.*.*"                     # Component Names:
+      - "$.paths.*.*.operationId"              # OperationIds:
+    then:
+      function: camara-reserved-words
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-parameters-descriptions:
+    message: "Parameter description is missing or empty: {{error}}"
+    severity: warn
+    description: |
+      This Spectral rule ensures that each parameter in the API specification, including components and properties, has a descriptive and meaningful description.
+    given:
+      - "$.components.*.*"
+      - "$.components.*.*.properties.*"
+    then:
+      field: description
+      function: truthy
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-operation-summary:
+    message: "Operation Summary Warning: Each operation should include a short summary for better understanding."
+    severity: warn
+    description: |
+            This rule checks if each operation (POST, GET, DELETE, PUT, PATCH, OPTIONS) in your API specification has a meaningful summary.
+            Ensure that you have added a 'summary' field for each operation in your OpenAPI specification.
+    given:
+      - "$.paths.*.post"
+      - "$.paths.*.get"
+      - "$.paths.*.delete"
+      - "$.paths.*.put"
+      - "$.paths.*.patch"
+      - "$.paths.*.options"
+    then:
+      field: summary
+      function: truthy
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-discriminator-use:
+    description: |
+      Ensure that API definition YAML files with oneOf or anyOf sections include a discriminator object for serialization, deserialization, and validation.
+    severity: warn
+    given: "$..[?(@.oneOf || @.anyOf)]"
+    then:
+      field: discriminator
+      function: truthy
+      description: "Discriminator object is required when using oneOf or anyOf."
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-operationid-casing-convention:
+    message: Operation Id must be in Camel case "{{error}}"
+    severity: hint
+    description: |
+        This rule checks Operation ids should follow a specific case convention: camel case.
+    given: "$.paths.*.*.operationId"
+    then:
+      function: casing
+      functionOptions:
+        type: camel
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-schema-casing-convention:
+    description: This rule checks schema should follow a specific case convention pascal case.
+    message: "{{property}} should be pascal case (UppperCamelCase)"
+    severity: warn
+    given: $.components.schemas[*]~
+    then:
+      function: casing
+      functionOptions:
+        type: pascal
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-parameter-casing-convention:
+    description: This rule checks Paths should follow a specific case convention kebab-case.
+    severity: error
+    message: "{{property}} should be kebab-case: {{error}}"
+    given: $.paths[*]~
+    then:
+      function: casing
+      functionOptions:
+        type: kebab
+    recommended: true  # Set to true/false to enable/disable this rule

artifacts/linting_rules/lint_function/camara-language-avoid-telco.js

@@ -0,0 +1,37 @@
+const replacements = [
+  { original: 'UE', recommended: 'device' },
+  { original: 'MSISDN', recommended: 'phone number' },
+  { original: 'mobile network', recommended: 'network' }
+];
+
+export default async function (input) {
+  const errors = [];
+  const suggestions = [];
+
+  // Iterate over properties of the input object
+  for (const path in input) {
+    const value = input[path];
+
+    // Check if the value is a string
+    if (typeof value === 'string') {
+      for (const replacement of replacements) {
+        const original = replacement.original;
+        const recommended = replacement.recommended;
+
+        // Use a regular expression to match 'original' as a standalone word
+        const regex = new RegExp(`\\b${original}\\b`, 'g');
+
+        // Check if 'original' exists in the value
+        if (regex.test(value)) {
+          errors.push(replacement);
+          suggestions.push(` Telco-specific terminology found in input: Consider replacing '${original}' with '${recommended}'.`);
+        }
+      }
+    }
+  }
+
+ // Check if any word from 'replacements' is in the suggestions
+  if (errors.length > 0) {
+    console.log(`Hint     camara-language-avoid-telco ` + suggestions.join(', '));
+  }
+};

artifacts/linting_rules/lint_function/camara-reserved-words.js

@@ -0,0 +1,95 @@
+const reservedWords = [
+  'abstract',
+  'apiclient',
+  'apiexception',
+  'apiresponse',
+  'assert',
+  'boolean',
+  'break',
+  'byte',
+  'case',
+  'catch',
+  'char',
+  'class',
+  'configuration',
+  'const',
+  'continue',
+  'do',
+  'double',
+  'else',
+  'extends',
+  'file',
+  'final',
+  'finally',
+  'float',
+  'for',
+  'goto',
+  'if',
+  'implements',
+  'import',
+  'instanceof',
+  'int',
+  'interface',
+  'list',
+  'localdate',
+  'localreturntype',
+  'localtime',
+  'localvaraccept',
+  'localvaraccepts',
+  'localvarauthnames',
+  'localvarcollectionqueryparams',
+  'localvarcontenttype',
+  'localvarcontenttypes',
+  'localvarcookieparams',
+  'localvarformparams',
+  'localvarheaderparams',
+  'localvarpath',
+  'localvarpostbody',
+  'localvarqueryparams',
+  'long',
+  'native',
+  'new',
+  'null',
+  'object',
+  'offsetdatetime',
+  'package',
+  'private',
+  'protected',
+  'public',
+  'return',
+  'short',
+  'static',
+  'strictfp',
+  'stringutil',
+  'super',
+  'switch',
+  'synchronized',
+  'this',
+  'throw',
+  'throws',
+  'transient',
+  'try',
+  'void',
+  'volatile',
+  'while'
+];
+// Reserved word 'enum' and 'default' are removed from above reserved word array as they are common in openAPI keyword
+export default async function lintReservedWords(input) {
+  // Iterate over properties of the input object
+  for (const path in input) {
+    if (typeof path === 'string') {
+
+      for (const word of reservedWords) {
+        const regex = new RegExp(`\\b${word}\\b`, 'g');  // Use a regular expression to match 'word' as a standalone word
+
+        if (regex.test(path)) {
+          const warningRuleName = 'camara-reserved-words';
+          const description = `Reserved words found in input: Consider avoiding the use of reserved word '${word}'`;
+         // const location = `${path}`;
+
+          console.log(`warning  ${warningRuleName}  ${description}  ${path}`);
+        }
+      }
+    }
+  }
+}

artifacts/linting_rules/lint_function/camara-security-no-secrets-in-path-or-query-parameters.js

@@ -0,0 +1,23 @@
+const sensitiveData = ['MSISDN','IMSI','phoneNumber'];
+
+export default async function (input) {
+
+  // Iterate over properties of the input object
+  for (const path in input) {
+
+    if (typeof path === 'string') {
+      for (const word of sensitiveData ) {
+        const regex = new RegExp(`\\b${word}\\b`, 'g');  // Use a regular expression to match 'word' as a standalone word
+
+           if (regex.test(path)) {
+
+              const warningRuleName = 'camara-security-no-secrets-in-path-or-query-parameters';
+              const description = `sensitiveData  Data found in path: Consider avoiding the use of sensitiveData  data '${word}'`;
+              const location = `paths.${path}`;
+              console.log(`warning  ${warningRuleName}  ${description}  ${location}`);
+
+        }
+      }
+    }
+  }
+}