A team can follow an API style guide and still miss a rule buried among its conventions. API linting checks API definition files against executable rules derived from that guide. It gives designers fast, repeatable feedback without requiring them to remember every guideline or wait for a manual review. section 3.1
A linter takes a definition file and a ruleset, then reports problems with their location and the rule violated. Run it in an API design editor or from the command line while designing; run it again in continuous integration when the definition is committed. Spectral is one option for JSON or YAML definitions, with a CLI and editor integrations. section 3.3 section 3.1
Turn a style guide into checks in stages:
- Start with a ruleset. In Spectral, a rule uses a JSONPath expression to select definition elements and a function to check them; rulesets can import other local or remote rulesets. section 3.12
- Set the severity to reflect policy. Distinguish mandatory guidelines from optional ones when choosing ERROR, WARN, or HINT, and agree which results should fail the build. section 8.11.4
- Handle existing APIs deliberately. Spectral overrides can turn a rule off or change its severity for a specified file and object, allowing new changes to meet current standards while older endpoints are assessed separately. section 3.9
A pull-request check
A GitHub Actions job can run `npx @stoplight/spectral-cli lint` on an OpenAPI file with `--ruleset` pointing to the project’s ruleset. A passing run reports, “No results with a severity of 'error' found!” For a failure, make the offending definition location and guideline easy to find, and block the pull request until the required check passes. section 8.5.3 section 8.11.3
Linting can also flag design-time security concerns, such as an HTTP server URL where a rule requires HTTPS or response schemas that may expose sensitive fields. These are checks of the definition, not a replacement for testing an implemented API. Some judgments—whether a description is meaningful, for example—are difficult to express as ordinary Spectral rules. Custom functions or LLM-assisted checks may help, while human design review remains important for questions automation cannot settle. section 10.2.9 section 10.2.4 section 3.11 section 1.6
