OpenAPI Validator: Redocly and Spectral in CI

Choose an OpenAPI validator by the failure you need to prevent. Redocly CLI provides document checks and configurable rules. Spectral provides a ruleset-based linter for JSON and YAML, including OpenAPI. Either can support a useful CI check. You do not need both unless each has a defined job. Neither static lint command proves that your deployed API enforces the description.

The configurations below follow the tools' official documentation. They are setup examples, not results from a comparative benchmark. Start with one owned API description and retain its referenced files. Do not paste private contracts or credentials into an unapproved online validator.

Which check answers your question?

A missing operationId illustrates the distinction. OpenAPI does not require one on every operation. Your team can require it for stable tooling. Label that diagnostic as a team rule, not a syntax error.

How do you configure Redocly CLI?

Use the Redocly installation instructions and the package's supported Node version. Install the selected CLI as an exact development dependency and commit the lockfile. In redocly.yaml, use:

extends:
  - recommended
rules:
  no-unresolved-refs: error
  operation-operationId: error

With @redocly/cli installed locally, run:

./node_modules/.bin/redocly lint openapi.yaml \
  --config redocly.yaml --lint-config error

The lint command uses the selected configuration. The reference rule checks that references resolve. The operation identifier rule makes a missing identifier an error here. The recommended ruleset also contains other checks, so inspect its diagnostics before adopting it as your release policy. Do not suppress the entire ruleset to clear one intentional exception.

How do you configure Spectral?

Install @stoplight/spectral-cli locally as an exact development dependency. Spectral needs a ruleset. Its official ruleset guide documents the built-in spectral:oas extension. Put this in .spectral.yaml:

extends:
  - spectral:oas
rules:
  operation-operationId: error

Run the local binary with an explicit threshold:

./node_modules/.bin/spectral lint openapi.yaml \
  --ruleset .spectral.yaml --fail-severity error

The Spectral CLI reference distinguishes displayed diagnostics from failure severity. With this threshold, warnings can remain visible without failing the command. --fail-severity warn also fails on warnings; it is a stricter setting. Review that choice instead of treating any printed warning as a failed build.

How do you make the CI result useful?

1. Install from the committed lockfile in an isolated job. Record the CLI version and ruleset revision. Avoid downloading an unpinned tool release on each run.
2. Lint the intended entry file with its complete reference set. Treat missing files, parser failures, and failed commands as failures, not empty successful reports.
3. Maintain deliberate invalid fixtures: an unresolved reference, a missing operation identifier, and a malformed schema. Confirm that the configured checks detect the expected errors. Keep a valid fixture too.
4. Review exceptions individually. Record the rule, location, reason, owner, and recheck condition.

Treat custom rule functions and plugins as executable dependencies. A local CLI can also fetch remote references. Use reviewed configuration, restricted file access, and controlled network access when evaluating an unfamiliar description.

For runtime coverage, use synthetic accounts in an owned or explicitly authorized environment. Check a valid request, a schema-invalid request, a missing token, and an authenticated caller without permission. Inspect stored changes as well as status codes. A valid schema cannot establish tenant ownership. Use the API endpoint inventory to connect static checks to the routes and workers that need runtime evidence.