feat: openapi lint

.spectral.yml

@@ -0,0 +1,16 @@
+# References to the rules 
+# OpenAPI: https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#openapi-rules
+# OWASP Top 10: https://apistylebook.stoplight.io/docs/owasp-top-10
+# Documentations: https://github.com/stoplightio/spectral-documentation/blob/main/src/ruleset.ts
+
+# cspell: words OWASP owasp
+
+# Use CDN hosted version for spectral-documentation and spectral-owasp
+extends:
+- 'spectral:oas'
+- 'https://unpkg.com/@stoplight/[email protected]/dist/ruleset.mjs'
+- 'https://unpkg.com/@stoplight/[email protected]/dist/ruleset.mjs'
+
+# Ignoring rules example
+# rules:
+#   docs-tags: off

Earthfile

@@ -49,3 +49,8 @@ edit-docs:
     LOCALLY
 
     RUN ./earthly/docs/dev/local.py cat-ci-docs:latest
+
+# check-lint-openapi - OpenAPI linting from a given directory
+check-lint-openapi: 
+    FROM ./earthly/spectral+spectral-base
+    DO ./earthly/spectral+BUILD_SPECTRAL --dir="./examples/openapi" --file_type="json"

docs/src/guides/json_yaml_linter.md

@@ -0,0 +1,57 @@
+---
+icon: material/star-check-outline
+---
+
+<!-- cspell: words OWASP -->
+
+# Spectral / JSON and YAML Linter
+
+JSON and YAML files can be linted with custom rules
+using [Spectral](https://github.com/stoplightio/spectral).
+The goal of using this linter is to ensure that best practice is followed.
+
+## Configuration
+
+Each repo will need one configuration file in the root of the repository.
+
+* `.spectral.yml` - Configures rules, which can be
+used to lint the JSON or YAML files.
+
+There are rules available to be used or customization is possible too.
+For more information, please visit [Spectral Document](https://meta.stoplight.io/docs/spectral/e5b9616d6d50c-rulesets)
+
+## Usage
+
+The linter can be used in different purpose,
+so a `FUNCTION` named `BUILD_SPECTRAL` is implemented
+to make it suit the purpose.
+
+`BUILD_SPECTRAL` contains four main arguments
+
+* `file_type`: the file type that will be lint.
+If it is set to `json`, minifying the JSON files will be performed.
+JSON and YAML linting are not allowed simultaneously to prevent conflicts.
+  Enforcing separate linting
+ensures accurate analysis for each file type in a folder, avoiding errors.
+* `dir`: A directory that contains files to be lint.
+* `src`: The root directory
+* `rule_set`: Rules set that is used
+
+## Example
+
+The example of using the linter can be found in [link](/Earthfile).
+The target `check-lint-openapi` is currently used for linting OpenAPI JSON file.
+The current rules set that is being used are:
+
+* [OWASP TOP 10](https://apistylebook.stoplight.io/docs/owasp-top-10)
+* [Spectral Documentation](https://github.com/stoplightio/spectral-documentation)
+* [OpenAPI](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#openapi-rules)
+
+The example of OpenAPI documentation can be found in [link](/examples/openapi/example.json).
+<!-- markdownlint-disable max-one-sentence-per-line -->
+!!! Warning
+    Please note that this OpenAPI documentation provided
+    in this repository is used for example purposes only.
+<!-- markdownlint-enable max-one-sentence-per-line -->
+For more information about OpenAPI Specification, please visit the
+official [documentation](https://swagger.io/specification/#components-object).

earthly/spectral/Earthfile

@@ -0,0 +1,31 @@
+VERSION --global-cache --use-function-keyword 0.7
+
+# cspell: words ruleset
+
+spectral-base:
+    FROM stoplight/spectral
+    WORKDIR /work
+    COPY . .
+    RUN chmod +x ./minify-json.sh
+    SAVE ARTIFACT minify-json.sh
+
+BUILD_SPECTRAL:
+    FUNCTION
+
+    # Specify what file type to lint 
+    ARG file_type = "json"
+    ARG dir = .
+    ARG src = .
+    # Rule set for spectral
+    ARG rule_set=.spectral.yml
+
+    COPY $src .
+
+    COPY +spectral-base/minify-json.sh minify-json.sh
+    # If file type is json, minify the JSON
+    RUN ./minify-json.sh
+
+    RUN spectral \
+        lint \
+        $dir/"**/*.{yml,json}" \
+        --ruleset $rule_set

earthly/spectral/Readme.md

@@ -0,0 +1,3 @@
+# Spectral / JSON and YAML Linter
+
+See [link](/docs/src/guides/json_yaml_linter.md) for the references.

earthly/spectral/minify-json.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+
+# Minify all JSON in the directory if the file type is json
+# Check if FILE_TYPE and DIR are not empty
+if [[ -n "${file_type}" ]] && [[ -n "${dir}" ]]; then
+    # Minify all JSON in the directory if the file type is json
+    if [[ "${file_type}" == "json" ]]; then
+        # Loop through each JSON file in the directory
+        for json_file in "${dir}"/*.json; do
+            # Check if the file is a regular file
+            if [[ -f "${json_file}" ]]; then
+                # Minify the JSON file using jq and overwrite the original file
+                jq -c . "${json_file}" > "${json_file}.tmp" && mv "${json_file}.tmp" "${json_file}"
+                echo "Compacted: ${json_file}"
+            fi
+        done
+    else
+        echo "File type is not JSON."
+    fi
+else
+    echo "FILE_TYPE or DIR is empty."
+fi