Add Spectral lint CI gate for openapi.yaml

[MillerMedia]

Summary

• Adds .spectral.yaml at repo root, mirroring the ruleset used for other Comfy-Org service specs (spectral:oas plus custom rules for snake_case property names, camelCase operationIds, error-response shape, path-param descriptions, and schema descriptions).
• Adds .github/workflows/openapi-lint.yml — runs @stoplight/spectral-cli@6 on PRs that touch openapi.yaml or the ruleset, at --fail-severity=error. Blocking from day 1 (no continue-on-error transitional period).
• Stacked on Add OpenAPI 3.1 specification for ComfyUI API #13397 — retargets to master automatically once that PR merges.

Current state of the spec

Running the ruleset locally against openapi.yaml at the tip of this branch:

✖ 4 problems (0 errors, 3 warnings, 0 infos, 1 hint)

Zero errors, so the gate passes. The 4 remaining findings are all known non-blocking items:

• /ws GET — operation-success-response (WebSocket returns 101, no 2xx response)
• PromptErrorResponse — loose error-response schema (hint)
• ModelFile.pathIndex — snake_case warning on a wire field
• ProgressTextWsMessage.nodeId — snake_case warning on a wire field

The two snake_case fields and the error shape are constrained by wire compatibility, and the /ws handshake can't express a 101 in OpenAPI cleanly.

Test plan

• CI runs the new OpenAPI Lint job on this PR
• Job passes (0 errors)
• Verify the workflow is skipped on PRs that don't touch openapi.yaml / .spectral.yaml
• Verify the workflow fails on a deliberately broken spec (e.g. temporarily introduce a duplicate operationId)

API Node PR Checklist

Scope

• Is API Node Change

Pricing & Billing

• Need pricing update
• No pricing update

If Need pricing update:

• Metronome rate cards updated
• Auto‑billing tests updated and passing

QA

• QA done
• QA not required

Comms

• Informed Kosinkadink

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	yarl@​1.23.0

View full report

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b10041ef-c2a1-4106-919e-a73483c54f2e

📥 Commits

Reviewing files that changed from the base of the PR and between 7ae5341 and 2cf262f.

📒 Files selected for processing (1)

• .github/workflows/openapi-lint.yml

✅ Files skipped from review due to trivial changes (1)

• .github/workflows/openapi-lint.yml

---

📝 Walkthrough

Walkthrough

Adds automated OpenAPI linting: a GitHub Actions workflow that runs on pull requests touching `openapi.yaml`, `.spectral.yaml`, or the workflow file. The job checks out the repo, sets up Node.js 20, installs `@stoplight/spectral-cli@6`, and runs Spectral against `openapi.yaml`, failing on error-severity findings. Also adds `.spectral.yaml` which extends `spectral:oas`, adjusts severities, and defines custom rules for property naming, operationId format, response schemas, path parameter descriptions, and component schema descriptions.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding a Spectral lint CI gate for openapi.yaml validation.
Description check	✅ Passed	The description clearly relates to the changeset, explaining the purpose of both new files, the ruleset logic, current test results, and verification steps.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Review rate limit: 1/5 review remaining, refill in 39 minutes and 55 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/openapi-lint.yml:
- Around line 3-13: Add an explicit least-privilege permissions block to the
workflow: under the top-level workflow config (where "on: pull_request" is
declared) add a permissions stanza setting "contents: read" so the "spectral"
job runs with read-only token scope; update the workflow to include the new
permissions entry rather than relying on repo/org defaults.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9db5bd20-688b-4b89-a797-d3cefbaf1231

📥 Commits

Reviewing files that changed from the base of the PR and between a164c82 and 14ada4d.

📒 Files selected for processing (2)

• .github/workflows/openapi-lint.yml
• .spectral.yaml