feat: add API descriptor with API_SPECTRAL with AsyncAPI/OpenAPI supp…

…ort (oxsecurity#3474)

Add API descriptor as modified copy of the OPENAPI descriptor.
Deprecate the contained linter OPENAPI_SPECTRAL.

Add `.spectral.yaml` as default config file to `TEMPLATE/`
as modified copy of `.openapirc.yml` with rulesets for
AsyncAPI and OpenAPI (previously, only OpenAPI).

Closes: oxsecurity#3387

.automation/test/api/api_bad_1.yml

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

.automation/test/api/api_bad_2.json

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

.automation/test/api/api_good_1.yml

@@ -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 mega-linter
+servers:
+  - url: "http://localhost:3000"
+paths: {}
+tags:
+  - name: example

.automation/test/api/api_good_2.json

@@ -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 mega-linter"
+  },
+  "servers": [
+    {
+      "url": "http://localhost:3000"
+    }
+  ],
+  "paths": {},
+  "tags": [
+    {
+      "name": "example"
+    }
+  ]
+}

.automation/test/api/reports/ERROR-API_SPECTRAL.txt

@@ -0,0 +1,28 @@
+Results of spectral linter (version 5.6.0)
+See documentation on https://megalinter.io/descriptors/openapi_spectral/
+-----------------------------------------------
+
+[ERROR] .automation/test/api/api_bad_1.yml
+    OpenAPI 3.x detected
+
+    .automation/test/api/api_bad_1.yml
+     1:1  warning  info-contact      Info object should contain `contact` object.
+     1:1  warning  info-description  OpenAPI object info `description` must be present and non-empty string.
+     1:1  warning  oas3-api-servers  OpenAPI `servers` must be present and non-empty array.
+     1:1    error  oas3-schema       Object should have required property `info`.
+     1:1  warning  openapi-tags      OpenAPI object should have non-empty `tags` array.
+
+    ✖ 5 problems (1 error, 4 warnings, 0 infos, 0 hints)
+
+[ERROR] .automation/test/api/api_bad_2.json
+    OpenAPI 3.x detected
+
+    .automation/test/api/api_bad_2.json
+     1:1  warning  info-contact      Info object should contain `contact` object.
+     1:1  warning  info-description  OpenAPI object info `description` must be present and non-empty string.
+     1:1  warning  oas3-api-servers  OpenAPI `servers` must be present and non-empty array.
+     1:1    error  oas3-schema       Object should have required property `info`.
+     1:1  warning  openapi-tags      OpenAPI object should have non-empty `tags` array.
+
+    ✖ 5 problems (1 error, 4 warnings, 0 infos, 0 hints)
+

.automation/test/api/reports/SUCCESS-API_SPECTRAL.txt

@@ -0,0 +1,12 @@
+Results of spectral linter (version 5.6.0)
+See documentation on https://megalinter.io/descriptors/api_spectral/
+-----------------------------------------------
+
+[SUCCESS] .automation/test/api/api_good_1.yml
+    OpenAPI 3.x detected
+    No results with a severity of 'error' or higher found!
+
+[SUCCESS] .automation/test/api/api_good_2.json
+    OpenAPI 3.x detected
+    No results with a severity of 'error' or higher found!
+

.automation/test/api/reports/expected-API.tap

@@ -0,0 +1,12 @@
+TAP version 13
+1..4
+not ok 1 - api_bad_1.yml
+  ---
+  message: OpenAPI 3.x detected\n\n/tmp/lint/.automation/test/api/api_bad_1.ymlopenapi\n 1 1  warning  info-contact      Info object should contain `contact` object.\n 1 1  warning  info-description  OpenAPI object info `description` must be present and non-empty string.\n 1 1  warning  oas3-api-servers  OpenAPI `servers` must be present and non-empty array.\n 1 1    error  oas3-schema       Object should have required property `info`.\n 1 1  warning  openapi-tags      OpenAPI object should have non-empty `tags` array.\n\n✖ 5 problems (1 error, 4 warnings, 0 infos, 0 hints)\n
+  ...
+not ok 2 - api_bad_2.json
+  ---
+  message: OpenAPI 3.x detected\n\n/tmp/lint/.automation/test/api/api_bad_2.jsonopenapi\n 1 1  warning  info-contact      Info object should contain `contact` object.\n 1 1  warning  info-description  OpenAPI object info `description` must be present and non-empty string.\n 1 1  warning  oas3-api-servers  OpenAPI `servers` must be present and non-empty array.\n 1 1    error  oas3-schema       Object should have required property `info`.\n 1 1  warning  openapi-tags      OpenAPI object should have non-empty `tags` array.\n\n✖ 5 problems (1 error, 4 warnings, 0 infos, 0 hints)\n
+  ...
+ok 3 - api_good_1.yml
+ok 4 - api_good_2.json

.cspell.json

@@ -521,6 +521,7 @@
         "asdict",
         "ashokm",
         "assignuser",
+        "asyncapi",
         "autocorrect",
         "autocrlf",
         "autofix",

.github/workflows/deploy-BETA-linters.yml

@@ -76,6 +76,7 @@ jobs:
           [
             "action_actionlint",
             "ansible_ansible_lint",
+            "api_spectral",
             "arm_arm_ttk",
             "bash_exec",
             "bash_shellcheck",

.github/workflows/deploy-DEV-linters.yml

@@ -47,6 +47,7 @@ jobs:
           [
             "action_actionlint",
             "ansible_ansible_lint",
+            "api_spectral",
             "arm_arm_ttk",
             "bash_exec",
             "bash_shellcheck",

.github/workflows/deploy-RELEASE-linters.yml

@@ -51,6 +51,7 @@ jobs:
           [
             "action_actionlint",
             "ansible_ansible_lint",
+            "api_spectral",
             "arm_arm_ttk",
             "bash_exec",
             "bash_shellcheck",

CHANGELOG.md

@@ -13,6 +13,7 @@ Note: Can be used with `oxsecurity/megalinter@beta` in your GitHub Action mega-l
 - Media
 
 - New linters
+  - `API_SPECTRAL` was added as replacement for `OPENAPI_SPECTRAL` (deprecated), supporting AsyncAPI and OpenAPI by default. Uses Spectral's standard config file name `.spectral.yaml` instead of `.openapirc.yml` with a default config with rulesets for AsyncAPI and OpenAPI enabled. Fixes [#3387](https://github.com/oxsecurity/megalinter/issues/3387)
 
 - Reporters
 

Dockerfile

@@ -206,6 +206,7 @@ WORKDIR /node-deps
 RUN npm --no-cache install --ignore-scripts --omit=dev \
                 @salesforce/cli \
                 typescript \
+                @stoplight/spectral-cli \
                 @coffeelint/cli \
                 jscpd \
                 stylelint \
@@ -241,7 +242,6 @@ RUN npm --no-cache install --ignore-scripts --omit=dev \
                 markdownlint-cli \
                 markdown-link-check \
                 markdown-table-formatter \
-                @stoplight/spectral-cli \
                 secretlint \
                 @secretlint/secretlint-rule-preset-recommend \
                 @secretlint/secretlint-formatter-sarif \

TEMPLATES/.spectral.yaml

@@ -0,0 +1,11 @@
+---
+
+#######################################
+#######################################
+## AsyncAPI and OpenAPI Linter rules ##
+#######################################
+#######################################
+
+extends:
+  - spectral:asyncapi
+  - spectral:oas

docs/descriptors/api.md

@@ -0,0 +1,39 @@
+---
+title: API linters in MegaLinter
+description: spectral is available to analyze API files in MegaLinter
+---
+<!-- markdownlint-disable MD003 MD020 MD033 MD041 -->
+<!-- @generated by .automation/build.py, please don't update manually -->
+<!-- Instead, update descriptor file at https://github.com/oxsecurity/megalinter/tree/main/megalinter/descriptors/api.yml -->
+# API
+
+## Linters
+
+| Linter                                                                | Additional                                                                                                                             |
+|-----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| [**spectral**](api_spectral.md)<br/>[_API_SPECTRAL_](api_spectral.md) | [![GitHub stars](https://img.shields.io/github/stars/stoplightio/spectral?cacheSeconds=3600)](https://github.com/stoplightio/spectral) |
+
+## Linted files
+
+- File extensions:
+  - `.yml`
+  - `.yaml`
+  - `.json`
+
+- Detected file content:
+  - `"asyncapi":`
+  - `"openapi":`
+  - `"swagger":`
+  - `asyncapi:`
+  - `openapi:`
+  - `swagger:`
+
+## Configuration in MegaLinter
+
+| Variable                 | Description                                     | Default value |
+|--------------------------|-------------------------------------------------|---------------|
+| API_PRE_COMMANDS         | List of bash commands to run before the linters | None          |
+| API_POST_COMMANDS        | List of bash commands to run after the linters  | None          |
+| API_FILTER_REGEX_INCLUDE | Custom regex including filter                   |               |
+| API_FILTER_REGEX_EXCLUDE | Custom regex excluding filter                   |               |
+