Add GitHub automation openapi linters

[yanchuk]

Motivation

As we add OpenAPI specs to this repository, we need to ensure they are properly validated. This PR adds automated linting to catch issues early.

Solution

• Added Spectral (by Stoplight) OpenAPI linter via GitHub Actions
• Configured .spectral.yaml with the standard OpenAPI ruleset
• Disabled oas3-valid-media-example rule to avoid false positives with JSON Lines (application/jsonl) format, which Spectral doesn't natively support

Changes

• Added .github/workflows/openapi-lint.yml - GitHub Action that runs on push/PR to main/master branches
• Added .spectral.yaml - Spectral configuration file

How to Test

Run locally:

npx @stoplight/spectral-cli lint "specs/*.openapi.yml"

also check https://github.com/mailtrap/mailtrap-openapi/actions

Expected output: 0 errors, a few non-critical warnings (unused components, missing servers array).

The GitHub Action will automatically run on every push/PR to validate all OpenAPI specs in the specs/ directory.

Summary by CodeRabbit

• Chores
  • Automated validation of OpenAPI specifications has been established to maintain API documentation standards and consistency.
  • Continuous validation now runs automatically on code changes affecting API specifications.
  • Configuration has been fine-tuned to support diverse content formats and media types in API documentation examples.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds GitHub Actions automation and configuration for OpenAPI specification linting using Spectral. A new workflow triggers on repository pushes and pull requests affecting the specs directory, installing Spectral and executing lint checks with verbose output. A Spectral configuration file extends the base OpenAPI ruleset while disabling the oas3-valid-media-example rule for non-JSON media types.

Changes

Cohort / File(s)	Summary
OpenAPI Linting Setup .github/workflows/openapi-lint.yml, .spectral.yaml	Introduces GitHub Actions workflow automating OpenAPI spec linting on pushes/PRs affecting specs directory; configures Spectral with Node.js 20 and disables oas3-valid-media-example rule to handle non-JSON media types

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify GitHub Actions workflow syntax and trigger conditions (push/PR filtering on specs directory and related config files)
• Confirm Node.js 20 version is appropriate for Spectral CLI
• Validate Spectral configuration file structure and ruleset extension
• Confirm the disabled rule (oas3-valid-media-example) appropriately addresses the jsonl/non-JSON media type validation concern

Poem

🐰 Hops through specs with Spectral's keen sight,
OpenAPI rules enforced day and night,
A workflow so swift, from push to deploy,
This automation brings hop-full joy! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add GitHub automation openapi linters' directly and concisely summarizes the main changes: adding GitHub Actions workflow for OpenAPI linting with Spectral configuration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch add-github-automation-openapi-linters

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

.github/workflows/openapi-lint.yml (2)

22-28: Consider adding npm caching for faster workflow runs.

The Node.js setup is correct, but adding cache configuration could speed up subsequent workflow runs.

🔎 Optional improvement to add npm caching

       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '20'
+          cache: 'npm'

Note: This requires a package.json or package-lock.json file in the repository root. If these don't exist, you can skip this optimization or use a different caching strategy.

---

30-31: Consider using npx instead of global installation.

While global installation works fine, using npx can simplify the workflow by avoiding the installation step altogether. This is a minor stylistic suggestion.

🔎 Alternative approach using npx

-      - name: Install Spectral
-        run: npm install -g @stoplight/spectral-cli
-
       - name: Lint OpenAPI Specs
-        run: spectral lint "specs/*.openapi.yml" --verbose
+        run: npx @stoplight/spectral-cli lint "specs/*.openapi.yml" --verbose

This approach automatically downloads and runs the latest compatible version without requiring a separate installation step.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c7238ef and a67ad4c.

📒 Files selected for processing (2)

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

🔇 Additional comments (3)

.github/workflows/openapi-lint.yml (2)

3-15: LGTM: Well-configured workflow triggers.

The trigger configuration is well thought out, running only when relevant paths change (specs, workflow file, or Spectral config). This prevents unnecessary workflow runs and saves CI resources.

---

30-34: The glob pattern "specs/*.openapi.yml" correctly matches all OpenAPI spec files in this repository. The specs directory contains only top-level files with no subdirectories, so the current pattern is sufficient and no changes are needed.

Likely an incorrect or invalid review comment.

.spectral.yaml (1)

1-7: Disabling the rule entirely is the correct approach for this use case.

The configuration is appropriate. Spectral's oas3-valid-media-example rule struggles with non-JSON media types like application/xml, and Spectral does not provide built-in options to exclude specific media types from validation. Attempting a more targeted approach would require creating a custom rule rather than modifying the built-in rule, which is more complex than the current solution.