How is linting different from validating?

Validation checks that the spec is structurally legal — it conforms to the OpenAPI standard. Linting checks that the spec is *good* — operationIds exist, descriptions are present, error responses are documented, tags group endpoints sensibly. A spec can pass validation and still have terrible documentation; the linter catches that.

What rules does the linter check?

Top-level: required openapi/swagger version, info.title, info.version, info.description, info.contact. Per-operation: operationId presence, operationId uniqueness, summary or description, tags, at least one response, at least one 2xx response, at least one 4xx response. Roughly two-dozen rules total — the same set Specway runs against your spec on every build.

Why does 'missing operationId' matter?

Almost every SDK generator (openapi-generator, openapi-typescript, oazapfts, etc.) uses operationId as the function name. Without one, generators fall back to method+path (like getApiV1UsersById) which is ugly and unstable across versions. operationId should be a stable camelCase identifier you control.

Why do I need a 4xx response if my API works?

Documenting error responses is for the *consumer*, not you. When a client gets a 400, they need to know the error response shape — what field has the message, whether it's structured. If you document only 2xx, every client has to reverse-engineer your error format from production traffic.

How do I run lint rules in CI?

Use Spectral (@stoplight/spectral) — the de facto OpenAPI linter. Install, configure with a .spectral.yaml, and run on every PR. Spectral has hundreds of built-in rules (this tool checks the most impactful ones). For full coverage, also use Specway, which runs Spectral plus its own quality checks on every spec import.

Why are some findings warnings and some info?

Errors break tooling (no responses, duplicate operationIds, missing version). Warnings hurt usability (no operationId, no descriptions). Info nudges quality (no contact info, no 4xx responses, no tags). Address errors first, work down. Most teams reach 'no errors, few warnings' within a sprint.

How is linting different from validating?

Validation checks that the spec is structurally legal — it conforms to the OpenAPI standard. Linting checks that the spec is *good* — operationIds exist, descriptions are present, error responses are documented, tags group endpoints sensibly. A spec can pass validation and still have terrible documentation; the linter catches that.

What rules does the linter check?

Top-level: required openapi/swagger version, info.title, info.version, info.description, info.contact. Per-operation: operationId presence, operationId uniqueness, summary or description, tags, at least one response, at least one 2xx response, at least one 4xx response. Roughly two-dozen rules total — the same set Specway runs against your spec on every build.

Why does 'missing operationId' matter?

Almost every SDK generator (openapi-generator, openapi-typescript, oazapfts, etc.) uses operationId as the function name. Without one, generators fall back to method+path (like getApiV1UsersById) which is ugly and unstable across versions. operationId should be a stable camelCase identifier you control.

Why do I need a 4xx response if my API works?

Documenting error responses is for the *consumer*, not you. When a client gets a 400, they need to know the error response shape — what field has the message, whether it's structured. If you document only 2xx, every client has to reverse-engineer your error format from production traffic.

How do I run lint rules in CI?

Use Spectral (@stoplight/spectral) — the de facto OpenAPI linter. Install, configure with a .spectral.yaml, and run on every PR. Spectral has hundreds of built-in rules (this tool checks the most impactful ones). For full coverage, also use Specway, which runs Spectral plus its own quality checks on every spec import.

Why are some findings warnings and some info?

Errors break tooling (no responses, duplicate operationIds, missing version). Warnings hurt usability (no operationId, no descriptions). Info nudges quality (no contact info, no 4xx responses, no tags). Address errors first, work down. Most teams reach 'no errors, few warnings' within a sprint.

Free Tool

OpenAPI Linter (2026)

Lint your OpenAPI / Swagger spec against documentation-quality rules. Catches missing operationIds, missing descriptions, undocumented errors, duplicate IDs, and more — issues that pass validation but break SDK generation and developer experience.

OpenAPI / Swagger spec

Validation vs linting

Validation checks that the document is legal OpenAPI. Linting checks that it's a good OpenAPI document. A spec can be 100% valid and still produce SDKs full of getApiV1UsersByIdEndpoint functions because operationIds are missing. Linting catches that.

Why these rules matter

operationId drives every code generator. Without it, function names regress to method+path and break on every refactor.
summary / description is what developers read in your docs. No description = sparse docs = support tickets.
tags group operations in rendered docs (Specway uses them as sidebar sections). No tags = wall of endpoints.
4xx responses tell consumers how errors look. Without them, every client reverse-engineers your error shape from production traffic.
info.contact tells stuck developers where to ask. Cheap to add, lossy to skip.

Linting in CI

For full rule coverage, install Spectral (@stoplight/spectral), commit a .spectral.yaml with your team's rules, and run on every PR. Or use Specway — it auto-runs Spectral plus internal quality checks on every spec import and surfaces issues alongside validation errors.

Ship API docs that stay this clean

Specway turns your OpenAPI spec into a branded developer portal — auto-synced, searchable, with built-in playground and code samples in every language. Free tier available.

Related tools

OpenAPI Validator

Check structural validity against the spec.

OpenAPI Viewer

Browse the operation list at a glance.

OpenAPI Diff

Compare two specs to find breaking changes.

OpenAPI → TypeScript

Generate TS types from OpenAPI schemas.

Frequently asked questions

Why these rules matter

operationId drives every code generator. Without it, function names regress to method+path and break on every refactor.
summary / description is what developers read in your docs. No description = sparse docs = support tickets.
tags group operations in rendered docs (Specway uses them as sidebar sections). No tags = wall of endpoints.
4xx responses tell consumers how errors look. Without them, every client reverse-engineers your error shape from production traffic.
info.contact tells stuck developers where to ask. Cheap to add, lossy to skip.

Why these rules matter

operationId drives every code generator. Without it, function names regress to method+path and break on every refactor.
summary / description is what developers read in your docs. No description = sparse docs = support tickets.
tags group operations in rendered docs (Specway uses them as sidebar sections). No tags = wall of endpoints.
4xx responses tell consumers how errors look. Without them, every client reverse-engineers your error shape from production traffic.
info.contact tells stuck developers where to ask. Cheap to add, lossy to skip.

Why these rules matter

operationId drives every code generator. Without it, function names regress to method+path and break on every refactor.
summary / description is what developers read in your docs. No description = sparse docs = support tickets.
tags group operations in rendered docs (Specway uses them as sidebar sections). No tags = wall of endpoints.
4xx responses tell consumers how errors look. Without them, every client reverse-engineers your error shape from production traffic.
info.contact tells stuck developers where to ask. Cheap to add, lossy to skip.