Skip to content

README.md

Latest commit

 

History

History
63 lines (52 loc) · 2.92 KB

README.md

File metadata and controls

63 lines (52 loc) · 2.92 KB
Raw

Elastic OpenAPI Linter

Lint an OpenAPI 2.0 (Swagger), 3.0, or 3.1 spec against the centralized Elastic ruleset (Spectral)

Inputs

Name Description Required Default
spec-path Repo-relative path to the OpenAPI spec file (JSON or YAML) true
fail-on-warn Fail the check on warning-level convention issues, not just errors false false

Outputs

Name Description
error-count Number of error-level results
warning-count Number of warning-level results
results-file Path to the machine-readable JSON results file

Usage

steps:
  - uses: actions/checkout@v6
    with:
      persist-credentials: false
  - uses: elastic/docs-actions/openapi/lint@v1
    with:
      spec-path: docs/openapi/api.yaml

Ruleset

The ruleset is centralized in this action (openapi/lint/ruleset.yaml) — consumers do not author their own rules. Rule changes are proposed via PR to elastic/docs-actions.

It has two severity tiers:

  • error — the spec parses, all $refs resolve, and it conforms to the OAS schema for its detected version (Swagger 2.0, OpenAPI 3.0.x, or OpenAPI 3.1.x). These always fail the check.
  • warn — authoring conventions, currently the generic hygiene rules built into spectral:oas (operationId presence, required descriptions/tags/servers, tags defined at root). These pass by default so existing specs aren't broken; set fail-on-warn: true to enforce them.

Elastic-specific conventions (operationId casing, security scheme naming, the x-state shape) aren't encoded as rules yet — they're sketched as commented-out examples in ruleset.yaml pending team agreement (see the analysis in elastic/docs-eng-team#639). Land them via PR once adopted.

spec-path should be repo-relative — PR annotations are anchored to the path as given, so an absolute path won't map back to a file in the diff.

This action installs Spectral via npm ci against a lockfile committed in this directory (openapi/lint/package-lock.json), pinning the full dependency tree — not just the CLI version — so lint results are reproducible run to run. It only calls the public npm registry and needs no secrets, so it's safe to run on fork PRs.

Note: an allowlist rule for x-* vendor extensions is planned as a follow-up and is not yet part of this ruleset.