Lint OpenAPI spec with vacuum #16
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: "Lint OpenAPI spec with vacuum" | |
| on: | |
| push: | |
| paths: | |
| - 'QuantConnect-Platform-2.0.0.yaml' | |
| pull_request: | |
| paths: | |
| - 'QuantConnect-Platform-2.0.0.yaml' | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pull-requests: write | |
| issues: write | |
| jobs: | |
| vacuum-lint: | |
| name: Run OpenAPI linting with vacuum | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Install vacuum | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: | | |
| curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh | |
| - name: Lint OpenAPI specification using vacuum | |
| id: lint | |
| shell: bash | |
| env: | |
| OPENAPI_PATH: "QuantConnect-Platform-2.0.0.yaml" | |
| SHOW_RULES: "false" | |
| MINIMUM_SCORE: "10" | |
| FAIL_ON_ERROR: "true" | |
| RULESET: "" | |
| PRINT_LOGS: "true" | |
| run: | | |
| args=( lint --pipeline-output "$OPENAPI_PATH" ) | |
| # --min-score <value> | |
| args+=( --min-score "$MINIMUM_SCORE" ) | |
| # --fail-severity none|error | |
| if [ "$FAIL_ON_ERROR" = "true" ]; then | |
| args+=( --fail-severity error ) | |
| else | |
| args+=( --fail-severity none ) | |
| fi | |
| # --show-rules only if show_rules == "true" | |
| if [ "$SHOW_RULES" = "true" ]; then | |
| args+=( --show-rules ) | |
| fi | |
| # optional ruleset | |
| if [ -n "$RULESET" ]; then | |
| args+=( --ruleset "$RULESET" ) | |
| fi | |
| echo "Running: vacuum ${args[*]}" | |
| set +e | |
| report=$(vacuum "${args[@]}") | |
| exit_code=$? | |
| set -e | |
| REPORT_FILE="$GITHUB_WORKSPACE/vacuum-lint-report.md" | |
| { | |
| echo "<!-- vacuum-lint-report -->" | |
| echo | |
| echo "$report" | |
| } > "$REPORT_FILE" | |
| # print logs to console if enabled | |
| if [ "$PRINT_LOGS" = "true" ]; then | |
| cat "$REPORT_FILE" | |
| fi | |
| echo "report_path=vacuum-lint-report.md" >> "$GITHUB_OUTPUT" | |
| echo "exit_code=$exit_code" >> "$GITHUB_OUTPUT" | |
| exit $exit_code | |
| - name: Create GitHub issue on failure | |
| if: failure() && github.event_name == 'workflow_dispatch' | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: | | |
| REPORT_FILE="$GITHUB_WORKSPACE/vacuum-lint-report.md" | |
| SUMMARY=$(sed -n '/| Category/,/^$/p' "$REPORT_FILE") | |
| BODY=$(cat <<EOF | |
| ## OpenAPI Lint Errors | |
| The \`vacuum\` linter found errors in \`QuantConnect-Platform-2.0.0.yaml\`. | |
| $SUMMARY | |
| **Run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} | |
| ## Steps to fix | |
| 1. Install vacuum locally: | |
| - **Linux/macOS:** \`curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh\` | |
| - **Windows:** download the latest release from https://github.com/daveshanley/vacuum/releases (e.g. \`vacuum_*_windows_x86_64.tar.gz\`), extract, and add to PATH. | |
| 2. Run vacuum to get the detailed error report: | |
| \`\`\` | |
| vacuum lint QuantConnect-Platform-2.0.0.yaml --fail-severity error | |
| \`\`\` | |
| 3. Fix each error in \`QuantConnect-Platform-2.0.0.yaml\`. Common issues: | |
| - \`oas3-schema\`: Using \`nullable: true\` (OpenAPI 3.0 style) instead of \`type: [string, "null"]\` (OpenAPI 3.1 style). | |
| - \`oas-schema-check\`: Fields listed in \`required\` that don't exist in \`properties\`, or invalid type values (e.g. \`type: int\` instead of \`type: integer\`). | |
| 4. Re-run vacuum to confirm no errors remain: | |
| \`\`\` | |
| vacuum lint QuantConnect-Platform-2.0.0.yaml --fail-severity error | |
| \`\`\` | |
| 5. Regenerate the API reference pages: | |
| \`\`\` | |
| python code-generators/API-Reference-Code-Generator.py | |
| \`\`\` | |
| EOF | |
| ) | |
| gh issue create \ | |
| --title "OpenAPI spec lint errors detected" \ | |
| --body "$BODY" \ | |
| --label "bug" |