API linting implementation guideline (#1)

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

@@ -0,0 +1,77 @@
+---
+# 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
+  # Pull Requests to main
+  pull_request:
+    branches: [master, main]
+
+env: # Comment env block if you do not want to apply fixes
+  # Apply linter fixes configuration
+  APPLY_FIXES: all # When active, APPLY_FIXES must also be defined as environment variable (in github/workflows/mega-linter.yml or other CI tool)
+  APPLY_FIXES_EVENT: pull_request # Decide which event triggers application of fixes in a commit or a PR (pull_request, push, all)
+  APPLY_FIXES_MODE: commit # If APPLY_FIXES is used, defines if the fixes are directly committed (commit) or posted in a PR (pull_request)
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: MegaLinter
+    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:oas Spectral Linting
+    #   run: spectral lint code/API_definitions/*.yaml --verbose --ruleset .spectral.yml
+        # Replace openapi.yaml file with your API specification file
+
+      # MegaLinter
+      - name: MegaLinter
+        id: ml
+        # You can override MegaLinter flavor used to have faster performances
+        # More info at https://megalinter.io/flavors/
+        uses: oxsecurity/megalinter/flavors/java@v7.3.0
+        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_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"
+          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@v4
+        with:
+          name: MegaLinter reports
+          path: |
+            megalinter-reports
+            mega-linter.log

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

@@ -0,0 +1,258 @@
+# 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
+  - 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: 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
+
+  # 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-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 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
+    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: hint
+    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: Paths should be kebab-case.
+    severity: error
+    message: "{{property}} is not kebab-case: {{error}}"
+    given: $.paths[*]~
+    then:
+      function: pattern
+      functionOptions:
+        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