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.

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

Lint passed? Ship the docs.

Specway builds the developer portal from the spec you just linted and checks it again on every push.

Publish this spec free See pricing

Free plan: 1 API, 1,000 views a month, no credit card, no time limit.

Interactive reference docs generated from your OpenAPI spec
Validation on every push, so an invalid spec never ships
Docs rebuild on their own every time the spec changes

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.

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

Ship API docs that stay this clean

Specway turns one OpenAPI spec into a hosted developer portal, an MCP server and llms.txt. When the spec changes, the docs follow.

Try Specway free

Free plan: 1 API, 1,000 views a month, no credit card, no time limit.

OpenAPI Linter (2026)

OpenAPI / Swagger spec

Lint passed? Ship the docs.

Specway builds the developer portal from the spec you just linted and checks it again on every push.

Publish this spec free See pricing

Free plan: 1 API, 1,000 views a month, no credit card, no time limit.

Interactive reference docs generated from your OpenAPI spec
Validation on every push, so an invalid spec never ships
Docs rebuild on their own every time the spec changes

Validation vs linting

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

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

Ship API docs that stay this clean

Specway turns one OpenAPI spec into a hosted developer portal, an MCP server and llms.txt. When the spec changes, the docs follow.

Try Specway free

Free plan: 1 API, 1,000 views a month, no credit card, no time limit.