openapi: Add openapi/lint composite action#207
Conversation
Adds a Spectral-based OpenAPI lint action with a centralized ruleset (error tier for parse/$ref/OAS-schema validity, warn tier for authoring conventions) covering Swagger 2.0, OpenAPI 3.0, and 3.1. The x- extension allowlist rule from the RFC is deferred to a follow-up issue. Closes elastic/docs-eng-team#639 (partial — allowlist follow-up tracked separately) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Cache ~/.npm/_npx keyed on the pinned spectral-cli version so npx doesn't cold-download the package on every run. - Replace three separate jq passes over the results file with one, and fold the unrecognized-format special case into a documented, extensible list of always-error diagnostic codes. - Merge the "Fail on results" step into the job-summary step, dropping the now-unnecessary intermediate step. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The custom elastic-* rules encoded specific conventions from the docs-eng-team#639 analysis (operationId casing, security scheme naming, x-state shape) that consumer teams haven't agreed to yet. Comment them out as examples instead of shipping them as active warn-tier rules; land each one via PR once its convention is adopted. The warn tier now only re-enables spectral:oas built-in hygiene rules (operationId presence, required descriptions/tags/servers). Updated the convention-warnings fixture to exercise those instead. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
| - '.github/workflows/test-openapi-lint.yml' | ||
|
|
||
| permissions: | ||
| contents: read |
There was a problem hiding this comment.
Q: Is it OK to have read here for the test workflow?
There was a problem hiding this comment.
No change needed — contents: read is correct here. This test workflow only checks out the repo (actions/checkout) and invokes the local composite action; it never writes to the repo, opens PRs, or calls other write-scoped APIs, so read-only is the right least-privilege setting.
| env: | ||
| SPEC_PATH: ${{ inputs.spec-path }} | ||
| FAIL_ON_WARN: ${{ inputs.fail-on-warn }} | ||
| run: | |
There was a problem hiding this comment.
Would set -euo pipefail be useful here?
There was a problem hiding this comment.
Fixed in 355df64 — added set -euo pipefail to all three composite-action shell steps (Validate inputs, Run Spectral, Write job summary), not just the one you flagged, so failures like a malformed jq/read fail loudly instead of silently continuing with empty values. The npx ... || EXIT=$? capture still works fine under set -e since it's the non-final side of an || list.
cotti
left a comment
cotti
left a comment
There was a problem hiding this comment.
LGTM, added a couple of points
elastic/docs-actions#207 and elastic#208 merged and v1 was tagged, so drop the placeholder commit-SHA pins in favor of the released tag.
2 participants
Closes https://github.com/elastic/docs-eng-team/issues/639
What
Adds
openapi/lint, a composite GitHub Action wrapping Spectral to lint OpenAPI specs (Swagger 2.0, OpenAPI 3.0.x, 3.1.x) against a centralized ruleset maintained in this repo.Why
Foundation work for the OpenAPI-to-S3 rollout (elastic/docs-eng-team#634, tracker #638). Closes elastic/docs-eng-team#639.
How
openapi/lint/ruleset.yaml: two-tier Spectral ruleset —errorfor parse/$ref/OAS-schema validity (non-negotiable),warnfor authoring conventions (operationId casing, security scheme names, required metadata,x-stateshape). Existing consumer specs pass as-is at the defaulterrorseverity;fail-on-warn: trueis the future enforcement lever.openapi/lint/action.yml: validates input, runsnpx @stoplight/spectral-cli(no secrets, fork-safe), emits PR annotations (-f github-actions) plus a machine-readable JSON summary, writes a job summary table, and fails per thefail-on-warninput.test-openapi-lint.ymlmatrix cover valid 2.0/3.0/3.1 specs, a broken$ref, a schema violation, convention-only warnings, and a non-OpenAPI file.Deferred to a follow-up: the
x-extension allowlist rule (RFC open question 3). Will file a separate docs-eng-team issue for it.Test plan
npx spectral lint) — all match expected pass/fail/warning counts.pre-commit runpasses (check-yaml, action-readme, actionlint).test-openapi-lintmatrix) green on this PR.Notes
Once merged, file the
x-extension allowlist as a follow-up issue referencing the seeded inventory in elastic/docs-eng-team#639.