speccy-spectral

Runs Stoplight Spectral's standard OAS ruleset and returns results in the shape Speccy consumes. Spectral and its rulesets are heavyweight, so this integration stays out of speccy-renderer and speccy-cli; hosts opt in by installing this package.

npm install speccy-spectral

Use

import { runSpectral } from 'speccy-spectral';

const diagnostics = await runSpectral(source);

runSpectral accepts a parsed OpenAPI document or raw YAML/JSON source text and resolves to SpectralDiagnosticInput[]: { code, message, severity, path, range } for each finding. Pass source text rather than a parsed object to preserve source ranges.

The result drops straight into speccy-core's analyzeOpenApi(document, { spectral }) or the renderer's spectralDiagnostics prop:

<Speccy spec={source} showDeveloperHints spectralDiagnostics={diagnostics} />

How Speccy uses it

The Docusaurus plugin imports it at build time and merges the output into the generated route's diagnostics during development builds, unless the route sets renderer.showDeveloperHints: false. The web studio imports it lazily in the browser so Spectral never lands in the initial bundle. Both patterns work: the package ships ESM and CJS builds and runs in Node and the browser.

Scope

The standard OAS ruleset only; there is no custom-ruleset or .spectral.yaml support. For custom rules, run Spectral yourself and pass the results through the same SpectralDiagnosticInput shape.

Decision 001 plans to fold this package into its consumers (#31). Prefer the renderer's spectralDiagnostics prop as the stable seam.

License

MIT