OpenAPI Linter

What this OpenAPI linter checks

The linter applies a small, transparent ruleset to the parsed API document. It requires basic API metadata and at least one path. Each operation should have a summary and stable operationId; operation IDs must be unique because generators frequently turn them into method names. Every operation needs at least one response, and a warning appears when none of the declared status codes is an explicit 2xx success response.

Path templates receive stricter checks. Every name inside braces, such as {userId}, must have a matching parameter with in: path. OpenAPI path parameters must set required: true, so the report treats a missing or false required flag as an error. The tool also warns when an OpenAPI 3 server URL begins with unencrypted HTTP. Local development servers may intentionally use HTTP; review that warning in context rather than changing a local workflow blindly.

Errors versus warnings

Errors represent structural or naming problems likely to break documentation, client generation, or request construction. Examples include a missing API title, duplicate operation IDs, an operation with no responses, and an undeclared path-template parameter. Warnings identify maintainability or publishing risks: missing summaries, missing operation IDs, no explicit success response, or an HTTP server URL.

A clean report means none of the supported rules found a problem. It does not certify the full OpenAPI schema. A team can still require tags, descriptions, examples, error envelopes, pagination conventions, security schemes, or custom extensions that this free linter intentionally does not enforce.

Use linting with validation and diffing

Validation, linting, and compatibility analysis answer different questions. The OpenAPI Validator checks whether the outer OpenAPI 3 structure contains required fields. This linter checks consistency and review quality. OpenAPI Diff compares a proposed contract with a baseline and classifies supported compatibility changes. Run all three on the exact generated artifact when a contract is produced by code or annotations.

For CI, keep rule behavior and tool versions pinned. If a warning becomes a team requirement, promote that policy in your repository’s dedicated linter configuration instead of assuming every API follows the same convention. Stable rules prevent unrelated pull requests from changing status merely because a hosted tool updated.

Privacy, YAML, and reference limits

Linting happens inside the current browser tab. Cryonel does not receive the pasted contract, follow its server URLs, execute examples, or resolve remote $ref documents. The built-in YAML reader handles ordinary mappings, lists, and scalar values; anchors, aliases, flow-style collections, tags, and multi-document streams may need conversion to JSON with a full YAML parser first.

Referenced parameters are skipped because their values are not available without resolution. Likewise, the linter does not recursively validate component schemas or verify that a running service matches its contract. Use a full OpenAPI validator and organization-specific rules before publishing a critical API. For ongoing change detection after review, Cryonel API Guard can monitor the contract and preserve change history.