API linting implementation guideline (#1)

artifacts/linting_rules/.github/workflows/megalinter.yml

@@ -1,6 +1,9 @@
 ---
 # MegaLinter GitHub Action configuration file
 # More info at https://megalinter.io
+# CAMARA Project - Github Action for Pull Reqests
+# 31.01.2024 - initial version
+
 name: MegaLinter
 
 on: # yamllint disable-line rule:truthy
@@ -31,16 +34,16 @@ jobs:
     steps:
       # Git Checkout
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           fetch-depth: 0 # If you use VALIDATE_ALL_CODEBASE = true, you can remove this line to improve performances
       - name: Install Spectral
         run: npm install -g @stoplight/spectral
       - name: Install Spectral functions
         run: npm install -g @stoplight/spectral-functions
-      - name: Run spectral:oas Spectral Linting
-        run: spectral lint code/API_definitions/openapi.yaml --verbose --ruleset .spectral.yml
+    # - name: Run spectral:oas Spectral Linting
+    #   run: spectral lint code/API_definitions/*.yaml --verbose --ruleset .spectral.yml
         # Replace openapi.yaml file with your API specification file
 
       # MegaLinter
@@ -52,19 +55,21 @@ jobs:
         env:
           # All available variables are described in documentation
           # https://megalinter.io/configuration/
+          PRINT_ALPACA: false
           # VALIDATE_ALL_CODEBASE: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} # Validates all source when push on main, else just the git diff with main. Override with true if you always want to lint all sources
           VALIDATE_ALL_CODEBASE: true
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           # ADD YOUR CUSTOM ENV VARIABLES HERE OR DEFINE THEM IN A FILE .mega-linter.yml AT THE ROOT OF YOUR REPOSITORY
           DISABLE: COPYPASTE,MARKDOWN
-          DISABLE_LINTERS: SPELL_CSPELL,SPELL_LYCHEE,YAML_PRETTIER,REPOSITORY_SEMGREP,REPOSITORY_DEVSKIM,REPOSITORY_KICS,REPOSITORY_TRIVY,REPOSITORY_CHECKOV,REPOSITORY_GITLEAKS,JAVA_PMD
+          DISABLE_LINTERS: SPELL_CSPELL,SPELL_LYCHEE,YAML_PRETTIER,REPOSITORY_GRYPE, REPOSITORY_SEMGREP,REPOSITORY_DEVSKIM,REPOSITORY_KICS,REPOSITORY_TRIVY,REPOSITORY_TRIVY_SBOM,REPOSITORY_TRUFFLEHOG,REPOSITORY_CHECKOV,REPOSITORY_GITLEAKS,YAML_V8R,JAVA_PMD,JAVA_CHECKSTYLE
           YAML_YAMLLINT_CONFIG_FILE: ".yamllint.yaml"
-          JAVA_CHECKSTYLE_CONFIG_FILE: "javalint.xml"
+          OPENAPI_SPECTRAL_CONFIG_FILE: ".spectral.yml"
+          YAML_YAMLLINT_FILTER_REGEX_INCLUDE: "(code/)"
 
           # Upload MegaLinter artifacts
       - name: Archive production artifacts
         if: ${{ success() }} || ${{ failure() }}
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: MegaLinter reports
           path: |

artifacts/linting_rules/.github/workflows/spectral_oas_lint.yml

@@ -0,0 +1,36 @@
+---
+# CAMARA Project - workflow configuration to manually run CAMARA OAS rules
+# see https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow
+# 31.01.2024 - initial version
+
+name: Spectral manual run
+
+on: workflow_dispatch
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Spectral linting
+    runs-on: ubuntu-latest
+    permissions:
+      # Give the default GITHUB_TOKEN write permission to commit and push, comment issues & post new PR
+      # Remove the ones you do not need
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      # Git Checkout
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0 # If you use VALIDATE_ALL_CODEBASE = true, you can remove this line to improve performances
+      - name: Install Spectral
+        run: npm install -g @stoplight/spectral
+      - name: Install Spectral functions
+        run: npm install -g @stoplight/spectral-functions
+      - name: Run Spectral linting
+        run: spectral lint code/API_definitions/*.yaml --verbose --ruleset .spectral.yml

artifacts/linting_rules/.spectral.yml

@@ -1,3 +1,7 @@
+# CAMARA Project - linting ruleset - documentation avaialable here:
+# https://github.com/camaraproject/Commonalities/blob/main/documentation/Linting-rules.md
+# 31.01.2024 - initial version
+
 extends: "spectral:oas"
 functions:
   - camara-reserved-words
@@ -36,15 +40,15 @@ rules:
   typed-enum: true
   oas3-api-servers: true
   oas3-examples-value-or-externalValue: true
-  oas3-operation-security-defined: true
+  oas3-operation-security-defined: false
   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
+  # oas3-server-variables: true
 
   # Custom Rules Utilizing Spectral's Built-in Functions and JavaScript Implementations
 
@@ -134,20 +138,62 @@ rules:
     then:
       function: camara-reserved-words
     recommended: true  # Set to true/false to enable/disable this rule
-
+
+   camara-routes-description:
+    message: "Functionality method description Warning: Each method should have description."
+    severity: warn
+    description: |
+            This rule checks if each operation (POST, GET, DELETE, PUT, PATCH, OPTIONS) in your API specification has a description.
+            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: description
+      function: truthy
+    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.
+      This Spectral rule ensures that each path parameter in the API specification has a descriptive and meaningful description.
+    given:
+      - "$.paths..parameters.*"
+    then:
+      field: description
+      function: truthy
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-response-descriptions:
+    message: "Parameter description is missing or empty: {{error}}"
+    severity: warn
+    description: |
+      This Spectral rule ensures that each responese object in the API specification has a descriptive and meaningful description.
+    given:
+      - "$.paths..responses.*"
+    then:
+      field: description
+      function: truthy
+    recommended: true  # Set to true/false to enable/disable this rule
+
+  camara-properties-descriptions:
+    message: "Property description is missing or empty: {{error}}"
+    severity: warn
+    description: |
+      This Spectral rule ensures that each propoerty within objects in the API specification 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
@@ -169,7 +215,7 @@ rules:
   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
+    severity: hint
     given: "$..[?(@.oneOf || @.anyOf)]"
     then:
       field: discriminator
@@ -201,12 +247,12 @@ rules:
     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.
+    description: Paths should be kebab-case.
     severity: error
-    message: "{{property}} should be kebab-case: {{error}}"
+    message: "{{property}} is not kebab-case: {{error}}"
     given: $.paths[*]~
     then:
-      function: casing
+      function: pattern
       functionOptions:
-        type: kebab
+        match: "^\/([a-z0-9]+(-[a-z0-9]+)*)?(\/[a-z0-9]+(-[a-z0-9]+)*|\/{.+})*$"  # doesn't allow /asasd{asdas}sadas pattern or not closed braces
     recommended: true  # Set to true/false to enable/disable this rule

artifacts/linting_rules/.yamllint.yaml

@@ -1,4 +1,6 @@
 ---
+# CAMARA Project - YAML linting configuration for yamllint https://yamllint.readthedocs.io/en/latest/rules.html
+# 31.01.2024 - initial version
 
 yaml-files:
   - '*.yaml'
@@ -11,6 +13,7 @@ rules:
   colons: enable
   commas: enable
   comments:
+    min-spaces-from-content: 1
     level: error
   comments-indentation:
     level: error
@@ -24,7 +27,8 @@ rules:
   key-ordering: disable
   line-length: disable
   new-line-at-end-of-file: enable
-  new-lines: enable
+  new-lines: 
+    type: platform
   octal-values: disable
   quoted-strings: disable
   trailing-spaces: enable