Merge pull request #286 from github/OpenAPI

Open api

.automation/test/openapi/README.md

@@ -0,0 +1,14 @@
+# OpenAPI Test Cases
+This folder holds the test cases for **OpenAPI**.  
+
+## Additional Docs
+The `_bad_` tests are valid `.yml`/`.json` but invalid OpenAPI specs.
+The test extensions used are `.ymlopenapi`/`.jsonopenapi` instead of `.yml`/`.json`. This is to prevent the [YAML] and [JSON] tests from picking them up.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/openapi/openapi_bad_1.ymlopenapi

@@ -0,0 +1 @@
+openapi: '3.0.0'

.automation/test/openapi/openapi_bad_2.jsonopenapi

@@ -0,0 +1,3 @@
+{
+  "openapi": "3.0.0"
+}

.automation/test/openapi/openapi_good_1.ymlopenapi

@@ -0,0 +1,13 @@
+openapi: 3.0.0
+info:
+  title: Example
+  version: '1.0'
+  contact:
+    name: Justin Kalland
+    email: justin@kalland.com
+  description: Test for super-linter
+servers:
+  - url: 'http://localhost:3000'
+paths: {}
+tags:
+  - name: example

.automation/test/openapi/openapi_good_2.jsonopenapi

@@ -0,0 +1,23 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Example",
+    "version": "1.0",
+    "contact": {
+      "name": "Justin Kalland",
+      "email": "justin@kalland.com"
+    },
+    "description": "Test for super-linter"
+  },
+  "servers": [
+    {
+      "url": "http://localhost:3000"
+    }
+  ],
+  "paths": {},
+  "tags": [
+    {
+      "name": "example"
+    }
+  ]
+}

.github/linters/.openapirc.yml

@@ -0,0 +1,9 @@
+---
+
+##########################
+##########################
+## OpenAPI Linter rules ##
+##########################
+##########################
+
+extends: spectral:oas

Dockerfile

@@ -72,6 +72,7 @@ RUN npm config set package-lock false \
       eslint-plugin-jest \
       stylelint \
       stylelint-config-standard \
+      @stoplight/spectral \
       && npm --no-cache install \
       markdownlint-cli \
       jsonlint prettyjson \
@@ -178,6 +179,7 @@ ENV GITHUB_SHA=${GITHUB_SHA} \
     VALIDATE_CLOJURE=${VALIDATE_CLOJURE} \
     VALIDATE_KOTLIN=${VALIDATE_KOTLIN} \
     VALIDATE_POWERSHELL=${VALIDATE_POWERSHELL} \
+    VALIDATE_OPENAPI=${VALIDATE_OPENAPI} \
     ANSIBLE_DIRECTORY=${ANSIBLE_DIRECTORY} \
     RUN_LOCAL=${RUN_LOCAL} \
     TEST_CASE_RUN=${TEST_CASE_RUN} \

README.md

@@ -55,6 +55,7 @@ Developers on **GitHub** can call the **GitHub Action** to lint their code base
 | **PowerShell**   | [PSScriptAnalyzer](https://github.com/PowerShell/Psscriptanalyzer)       |
 | **ENV**          | [dotenv-linter](https://github.com/dotenv-linter/dotenv-linter)          |
 | **Kotlin**       | [ktlint](https://github.com/pinterest/ktlint)                            |
+| **OpenAPI**      | [spectral](https://github.com/stoplightio/spectral)                      |
 
 ## How to use
 To use this **GitHub** Action you will need to complete the following:
@@ -162,6 +163,7 @@ and won't run anything unexpected.
 | **VALIDATE_ENV** | `true` | Flag to enable or disable the linting process of the language. |
 | **VALIDATE_CLOJURE** | `true` | Flag to enable or disable the linting process of the language. |
 | **VALIDATE_KOTLIN** | `true` | Flag to enable or disable the linting process of the language. |
+| **VALIDATE_OPENAPI** | `true` | Flag to enable or disable the linting process of the language. |
 | **ANSIBLE_DIRECTORY** | `/ansible` | Flag to set the root directory for Ansible file location(s). |
 | **ACTIONS_RUNNER_DEBUG** | `false` | Flag to enable additional information about the linter, versions, and additional output. |
 | **DISABLE_ERRORS** | `false` | Flag to have the linter complete with exit code 0 even if errors were detected. |

TEMPLATES/.openapirc.yml

@@ -0,0 +1,9 @@
+---
+
+##########################
+##########################
+## OpenAPI Linter rules ##
+##########################
+##########################
+
+extends: spectral:oas

docs/disabling-linters.md

@@ -24,6 +24,7 @@ Below are examples and documentation for each language and the various methods t
 - [CSS](#stylelint)
 - [ENV](#dotenv-linter)
 - [Kotlin](#kotlin)
+- [OpenAPI](#openapi)
 
 <!-- toc -->
 
@@ -610,6 +611,27 @@ import package.b.*
 
 --------------------------------------------------------------------------------
 
+## OpenAPI
+- [spectral](https://github.com/stoplightio/spectral)
+
+### OpenAPI Config file
+- `.github/linters/.openapirc.yml`
+- You can add, extend, and disable rules
+- Documentation at [Spectral Custom Rulesets](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/guides/4-custom-rulesets.md)
+- File should be located at: `.github/linters/.openapirc.yml`
+
+### OpenAPI disable single line
+- There is currently **No** way to disable rules inline of the file(s)
+
+### OpenAPI disable code block
+- There is currently **No** way to disable rules inline of the file(s)
+
+### OpenAPI disable entire file
+- There is currently **No** way to disable rules inline of the file(s)
+- However, you can make [rule exceptions](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/guides/6-exceptions.md?srn=gh/stoplightio/spectral/docs/guides/6-exceptions.md) in the config for individual file(s).
+
+--------------------------------------------------------------------------------
+
 ## Clojure
 - [clj-kondo](https://github.com/borkdude/clj-kondo)
 - Since clj-kondo approaches static analysis in a very Clojure way, it is advised to read the [configuration docs](https://github.com/borkdude/clj-kondo/blob/master/doc/config.md)

lib/linter.sh

@@ -54,6 +54,9 @@ POWERSHELL_LINTER_RULES="$DEFAULT_RULES_LOCATION/$POWERSHELL_FILE_NAME"    # Pat
 # CSS Vars
 CSS_FILE_NAME='.stylelintrc.json'                                   # Name of the file
 CSS_LINTER_RULES="$DEFAULT_RULES_LOCATION/$CSS_FILE_NAME"           # Path to the CSS lint rules
+# OpenAPI Vars
+OPENAPI_FILE_NAME='.openapirc.yml'                                   # Name of the file
+OPENAPI_LINTER_RULES="$DEFAULT_RULES_LOCATION/$OPENAPI_FILE_NAME"   # Path to the OpenAPI lint rules
 # Clojure Vars
 CLOJURE_FILE_NAME='.clj-kondo/config.edn'
 CLOJURE_LINTER_RULES="$DEFAULT_RULES_LOCATION/$CLOJURE_FILE_NAME"
@@ -64,8 +67,7 @@ CLOJURE_LINTER_RULES="$DEFAULT_RULES_LOCATION/$CLOJURE_FILE_NAME"
 LINTER_ARRAY=("jsonlint" "yamllint" "xmllint" "markdownlint" "shellcheck"
   "pylint" "perl" "rubocop" "coffeelint" "eslint" "standard"
   "ansible-lint" "/dockerfilelint/bin/dockerfilelint" "golangci-lint" "tflint"
-  "stylelint" "dotenv-linter" "powershell" "ktlint" "clj-kondo")
+  "stylelint" "dotenv-linter" "powershell" "ktlint" "clj-kondo" "spectral")
-
 
 #############################
 # Language array for prints #
@@ -73,7 +75,7 @@ LINTER_ARRAY=("jsonlint" "yamllint" "xmllint" "markdownlint" "shellcheck"
 LANGUAGE_ARRAY=('YML' 'JSON' 'XML' 'MARKDOWN' 'BASH' 'PERL' 'PHP' 'RUBY' 'PYTHON'
   'COFFEESCRIPT' 'ANSIBLE' 'JAVASCRIPT_STANDARD' 'JAVASCRIPT_ES'
   'TYPESCRIPT_STANDARD' 'TYPESCRIPT_ES' 'DOCKER' 'GO' 'TERRAFORM'
-  'CSS' 'ENV' 'POWERSHELL' 'KOTLIN' 'CLOJURE')
+  'CSS' 'ENV' 'POWERSHELL' 'KOTLIN' 'CLOJURE' 'OPENAPI')
 
 ###################
 # GitHub ENV Vars #
@@ -107,6 +109,7 @@ VALIDATE_CLOJURE="${VALIDATE_CLOJURE}"                # Boolean to validate lang
 VALIDATE_TERRAFORM="${VALIDATE_TERRAFORM}"            # Boolean to validate language
 VALIDATE_POWERSHELL="${VALIDATE_POWERSHELL}"          # Boolean to validate language
 VALIDATE_KOTLIN="${VALIDATE_KOTLIN}"                  # Boolean to validate language
+VALIDATE_OPENAPI="${VALIDATE_OPENAPI}"                # Boolean to validate language
 TEST_CASE_RUN="${TEST_CASE_RUN}"                      # Boolean to validate only test cases
 DISABLE_ERRORS="${DISABLE_ERRORS}"                    # Boolean to enable warning-only output without throwing errors
 
@@ -155,6 +158,7 @@ FILE_ARRAY_CSS=()                   # Array of files to check
 FILE_ARRAY_ENV=()                   # Array of files to check
 FILE_ARRAY_CLOJURE=()               # Array of files to check
 FILE_ARRAY_KOTLIN=()                # Array of files to check
+FILE_ARRAY_OPENAPI=()               # Array of files to check
 
 ############
 # Counters #
@@ -182,6 +186,7 @@ ERRORS_FOUND_CSS=0                  # Count of errors found
 ERRORS_FOUND_ENV=0                  # Count of errors found
 ERRORS_FOUND_CLOJURE=0              # Count of errors found
 ERRORS_FOUND_KOTLIN=0               # Count of errors found
+ERRORS_FOUND_OPENAPI=0              # Count of errors found
 
 ################################################################################
 ########################## FUNCTIONS BELOW #####################################
@@ -563,6 +568,42 @@ LintAnsibleFiles()
     fi
   fi
 }
+
+################################################################################
+#### Function DetectOpenAPIFile ################################################
+DetectOpenAPIFile()
+{
+  ################
+  # Pull in vars #
+  ################
+  FILE="$1"
+
+  ###############################
+  # Check the file for keywords #
+  ###############################
+  grep -E '"openapi":|"swagger":|^openapi:|^swagger:' "$GITHUB_WORKSPACE/$FILE" > /dev/null
+
+  #######################
+  # Load the error code #
+  #######################
+  ERROR_CODE=$?
+
+  ##############################
+  # Check the shell for errors #
+  ##############################
+  if [ $ERROR_CODE -eq 0 ]; then
+    ########################
+    # Found string in file #
+    ########################
+	  return 0
+  else
+    ###################
+    # No string match #
+    ###################
+	  return 1
+  fi
+}
+
 ################################################################################
 #### Function GetGitHubVars ####################################################
 GetGitHubVars()
@@ -764,6 +805,7 @@ GetValidationInfo()
   VALIDATE_ENV=$(echo "$VALIDATE_ENV" | awk '{print tolower($0)}')
   VALIDATE_CLOJURE=$(echo "$VALIDATE_CLOJURE" | awk '{print tolower($0)')
   VALIDATE_KOTLIN=$(echo "$VALIDATE_KOTLIN" | awk '{print tolower($0)}')
+  VALIDATE_OPENAPI=$(echo "$VALIDATE_OPENAPI" | awk '{print tolower($0)}')
 
   ################################################
   # Determine if any linters were explicitly set #
@@ -791,6 +833,7 @@ GetValidationInfo()
         -n "$VALIDATE_CSS" || \
         -n "$VALIDATE_ENV" || \
         -n "$VALIDATE_CLOJURE" || \
+        -n "$VALIDATE_OPENAPI" || \
         -n "$VALIDATE_KOTLIN" ]]; then
     ANY_SET="true"
   fi
@@ -1103,6 +1146,19 @@ GetValidationInfo()
     VALIDATE_KOTLIN="true"
   fi
 
+  #######################################
+  # Validate if we should check OPENAPI #
+  #######################################
+  if [[ "$ANY_SET" == "true" ]]; then
+    # Some linter flags were set - only run those set to true
+    if [[ -z "$VALIDATE_OPENAPI" ]]; then
+      # OPENAPI flag was not set - default to false
+      VALIDATE_OPENAPI="false"
+    fi
+  else
+    # No linter flags were set - default all to true
+    VALIDATE_OPENAPI="true"
+  fi
 
   #######################################
   # Validate if we should check Clojure #
@@ -1236,6 +1292,11 @@ GetValidationInfo()
   else
     PRINT_ARRAY+=("- Excluding [KOTLIN] files in code base...")
   fi
+  if [[ "$VALIDATE_OPENAPI" == "true" ]]; then
+    PRINT_ARRAY+=("- Validating [OPENAPI] files in code base...")
+  else
+    PRINT_ARRAY+=("- Excluding [OPENAPI] files in code base...")
+  fi
 
   ##############################
   # Validate Ansible Directory #
@@ -1419,6 +1480,12 @@ BuildFileList()
       # Append the file to the array #
       ################################
       FILE_ARRAY_YML+=("$FILE")
+      ############################
+      # Check if file is OpenAPI #
+      ############################
+      if DetectOpenAPIFile "$FILE"; then
+        FILE_ARRAY_OPENAPI+=("$FILE")
+      fi
       ##########################################################
       # Set the READ_ONLY_CHANGE_FLAG since this could be exec #
       ##########################################################
@@ -1431,6 +1498,12 @@ BuildFileList()
       # Append the file to the array #
       ################################
       FILE_ARRAY_JSON+=("$FILE")
+      ############################
+      # Check if file is OpenAPI #
+      ############################
+      if DetectOpenAPIFile "$FILE"; then
+        FILE_ARRAY_OPENAPI+=("$FILE")
+      fi
       ##########################################################
       # Set the READ_ONLY_CHANGE_FLAG since this could be exec #
       ##########################################################
@@ -2159,6 +2232,7 @@ Footer()
      [ "$ERRORS_FOUND_RUBY" -ne 0 ] || \
      [ "$ERRORS_FOUND_CSS" -ne 0 ] || \
      [ "$ERRORS_FOUND_ENV" -ne 0 ] || \
+     [ "$ERRORS_FOUND_OPENAPI" -ne 0 ] || \
      [ "$ERRORS_FOUND_CLOJURE" -ne 0 ] || \
      [ "$ERRORS_FOUND_KOTLIN" -ne 0 ]; then
     # Failed exit
@@ -2223,6 +2297,7 @@ RunTestCases()
   TestCodebase "ENV" "dotenv-linter" "dotenv-linter" ".*\.\(env\)\$"
   TestCodebase "CLOJURE" "clj-kondo" "clj-kondo --config $CLOJURE_LINTER_RULES --lint" ".*\.\(clj\|cljs\|cljc\|edn\)\$"
   TestCodebase "KOTLIN" "ktlint" "ktlint" ".*\.\(kt\|kts\)\$"
+  TestCodebase "OPENAPI" "spectral" "spectral lint -r $OPENAPI_LINTER_RULES" ".*\.\(ymlopenapi\|jsonopenapi\)\$"
 
   #################
   # Footer prints #
@@ -2579,6 +2654,29 @@ if [ "$VALIDATE_POWERSHELL" == "true" ]; then
   LintCodebase "POWERSHELL" "pwsh" "pwsh -c Invoke-ScriptAnalyzer -EnableExit -Settings $POWERSHELL_LINTER_RULES -Path" ".*\.\(ps1\|psm1\|psd1\|ps1xml\|pssc\|psrc\|cdxml\)\$" "${FILE_ARRAY_POWERSHELL[@]}"
 fi
 
+###################
+# OPENAPI LINTING #
+###################
+if [ "$VALIDATE_OPENAPI" == "true" ]; then
+  # If we are validating all codebase we need to build file list because not every yml/json file is an OpenAPI file
+  if [ "$VALIDATE_ALL_CODEBASE" == "true" ]; then
+    # shellcheck disable=SC2207
+    LIST_FILES=($(cd "$GITHUB_WORKSPACE" || exit; find . -type f -regex ".*\.\(yml\|yaml\|json\)\$" 2>&1))
+    for FILE in "${LIST_FILES[@]}"
+    do
+      if DetectOpenAPIFile "$FILE"; then
+        FILE_ARRAY_OPENAPI+=("$FILE")
+      fi
+    done
+  fi
+
+  ##########################
+  # Lint the OpenAPI files #
+  ##########################
+  # LintCodebase "FILE_TYPE" "LINTER_NAME" "LINTER_CMD" "FILE_TYPES_REGEX" "FILE_ARRAY"
+  LintCodebase "OPENAPI" "spectral" "spectral lint -r $OPENAPI_LINTER_RULES" "disabledfileext" "${FILE_ARRAY_OPENAPI[@]}"
+fi
+
 ##########
 # Footer #
 ##########