diff --git a/.automation/test/openapi/README.md b/.automation/test/openapi/README.md new file mode 100644 index 00000000..6f5d2c24 --- /dev/null +++ b/.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. diff --git a/.automation/test/openapi/openapi_bad_1.ymlopenapi b/.automation/test/openapi/openapi_bad_1.ymlopenapi new file mode 100644 index 00000000..6c86b1b4 --- /dev/null +++ b/.automation/test/openapi/openapi_bad_1.ymlopenapi @@ -0,0 +1 @@ +openapi: '3.0.0' diff --git a/.automation/test/openapi/openapi_bad_2.jsonopenapi b/.automation/test/openapi/openapi_bad_2.jsonopenapi new file mode 100644 index 00000000..b0b97ddb --- /dev/null +++ b/.automation/test/openapi/openapi_bad_2.jsonopenapi @@ -0,0 +1,3 @@ +{ + "openapi": "3.0.0" +} diff --git a/.automation/test/openapi/openapi_good_1.ymlopenapi b/.automation/test/openapi/openapi_good_1.ymlopenapi new file mode 100644 index 00000000..eb4924a1 --- /dev/null +++ b/.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 diff --git a/.automation/test/openapi/openapi_good_2.jsonopenapi b/.automation/test/openapi/openapi_good_2.jsonopenapi new file mode 100644 index 00000000..93f59635 --- /dev/null +++ b/.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" + } + ] +} diff --git a/.github/linters/.openapirc.yml b/.github/linters/.openapirc.yml new file mode 100644 index 00000000..fdf641e1 --- /dev/null +++ b/.github/linters/.openapirc.yml @@ -0,0 +1,9 @@ +--- + +########################## +########################## +## OpenAPI Linter rules ## +########################## +########################## + +extends: spectral:oas diff --git a/Dockerfile b/Dockerfile index 4dec22a8..d0c3a70b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -27,7 +27,7 @@ RUN apk add --no-cache \ libxml2-utils perl \ ruby ruby-dev ruby-bundler ruby-rdoc make \ py3-setuptools ansible-lint \ - go \ + go \ openjdk8-jre \ php7 \ ca-certificates less ncurses-terminfo-base \ @@ -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} \ diff --git a/README.md b/README.md index de10ad11..35d707ba 100644 --- a/README.md +++ b/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. | diff --git a/TEMPLATES/.openapirc.yml b/TEMPLATES/.openapirc.yml new file mode 100644 index 00000000..fdf641e1 --- /dev/null +++ b/TEMPLATES/.openapirc.yml @@ -0,0 +1,9 @@ +--- + +########################## +########################## +## OpenAPI Linter rules ## +########################## +########################## + +extends: spectral:oas diff --git a/docs/disabling-linters.md b/docs/disabling-linters.md index cf5bd831..408eba19 100644 --- a/docs/disabling-linters.md +++ b/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) @@ -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) diff --git a/lib/linter.sh b/lib/linter.sh index 5957ba15..65b973a1 100755 --- a/lib/linter.sh +++ b/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 # ##########