{
  "id": 12788705,
  "title": "Enforce an API style guide in CI with Spectral: custom rules that stop bad OpenAPI before it merges",
  "url": "https://urgent.news/2026/10/08/enforce-an-api-style-guide-in-ci-with-spectral-custom-rules-that-stop",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-10-08T04:43:43.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/jeff_pdc/enforce-an-api-style-guide-in-ci-with-spectral-custom-rules-that-stop-bad-openapi-before-it-merges-58da"
  },
  "original_language": "en",
  "account": "Every API program begins with a style guide document, but often ends up unread on a wiki while specifications accumulate duplicate operationId s, 200 responses lacking bodies, GET requests containing secrets in query strings, and numerous distinct error shapes. Linting turns the guide into a machine-readable set of rules that will prevent the pull request from merging. Spectral, the standard OpenAPI linter for this task, provides the value not from its built-in rules but from encoding your team's conventions once and enforcing them constantly. Run it locally and in Continuous Integration (CI) pipelines to ensure consistency. Spectral takes a ruleset file (in YAML or JavaScript format) and checks one or more documents: install the Spectral CLI using npm and run a lint command with the ruleset specified in the YAML file. A minimal CI step can fail the build on errors while allowing warnings to pass through. Add the same command to a pre-commit hook so that authors receive feedback before they submit their pull request.\n\nBegin by extending the OpenAPI recommended rules, then convert your style guide into explicit rules. Create a rules file (openapi/.spectral.yaml) that extends the spectral:oas rules and defines your own rules. For example, enforce proper documentation completeness (warnings during rollout), operationId conventions (operationId must be lowerCamelCase and verb-first, error), tag hygiene (Every used tag must be declared in the root tags array), error and response contract (Every 4xx/5xx response must reference the ProblemDetail schema), no secrets in query parameters, consistency (prefer an object envelope for top-level arrays), and array responses wrapped. Custom functions can be written for cross-field rules, such as ensuring every write operation that returns 202 also documents a Location header, and every enum used in a response has an unknown-value policy note. In these custom functions, use JSONPath-plus syntax for cross-field logic and define a given selector, assertion, and severity for each rule.",
  "summary": "Every API program starts with a style guide document, and most end with it unread in a wiki while specs quietly grow duplicate operationId s, 200 responses with no body, GET requests that take secrets in the query string, and a dozen subtly different error shapes. Linting turns the guide into something that actually runs: a machine-readable ruleset that fails the pull request. Spectral is the…",
  "key_points": [
    "Enforce API style guide in CI with Spectral",
    "Create custom rules to prevent bad OpenAPI before merging",
    "Use Spectral CLI and YAML ruleset file for linting"
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}