
OpenAPI: Lint, Format and Structure a Maintainable API
operationId, tags, error responses: practical rules that prevent spec debt when you lint and format OpenAPI files online.
Linting and formatting OpenAPI specs before merging
A spec can pass schema validation yet still ship without operationId, missing tags, or only a default response. That technical debt shows up weeks later, when SDK generators, API portals, or contract tests fail silently. Formatting alone does not fix those gaps, while linting catches the style and completeness rules that validators ignore. FastMinify's online OpenAPI linter applies a fixed Spectral-style subset to path operations, entirely in your browser. Pair it with the OpenAPI formatter for readable PR diffs and the OpenAPI validator for schema conformance. If structural errors block you first, start with our OpenAPI validation guide, then explore the API tools hub.
Honest limits and maintainable API design
A No blocking issues result means no issues in the v1 rule subset, not that your API is production-ready or fully documented.
These fields prevent spec debt that validators miss but generators and portals require.
operationId: stable, unique, camelCase, and never renamed without a deprecation plantags: group by domain or bounded context to match your developer portal sectionsinfo.description and info.contact: lint warns when they are missing, so fill them in for external APIs/pet-orders to /petOrders, since the kebab-case rule aligns with REST conventionsBrowser tools speed up feedback, while pipelines enforce org-wide policy.
$ref resolutionValidate, format, then lint in a design-first workflow
Do not swap steps during review, because each tool answers a different question about your OpenAPI file.
FastMinify lint is not full Spectral. It ships a fixed rule set focused on maintainable path operations (ADR-OAS-009).
not-openapi (error): the root must be OpenAPI 3.x with an info object, as an entry check before the other rulesinfo-contact (warning): info.contact should be presentinfo-description (warning): non-empty info.descriptionpaths-kebab-case (warning): path segments should be kebab-case or vNoperation-operationId (warning): every operation needs a non-empty operationIdoperation-tags (warning): at least one tag per operationoperation-description (warning): summary or description requiredoperation-success-response (error): at least one 2xx response, and default alone does not countpath-item-ref (warning): path item $ref not expanded in v1 lintAn honest scope: do not assume parity with Spectral, Redocly, or gateway policy engines.
webhooks and callbacks are out of scope in v1$ref URLs, so paste a self-contained specThe formatter rewrites JSON or YAML with a 2 or 4 space indent and can sort keys recursively for stable diffs.
openapi: 3.0 in YAML normalizes to string 3.0.0Lint and format OpenAPI, step by step
The OpenAPI linter parses JSON or YAML (max 512 KiB), checks the not-openapi entry rule, then runs path-operation rules. The result reads No blocking issues, Valid with warnings, or Blocking issues found, and it is never a plain green when warnings exist.
The OpenAPI formatter rewrites the document for human review. It formats automatically on paste, and the Format button (⌘↵) applies after manual edits.
Your mobile pipeline generates a client from the spec, and warnings you ignored become hard failures downstream.
Validate schema conformance
Paste it into validate-openapi. Fix Scalar errors first, because lint will not help on a structurally invalid spec.
Lint the path operations
Open lint-openapi. Resolve operation-operationId and operation-tags warnings on every public endpoint.
Format and open the PR
Run the fixed spec through format-openapi, with key sort if your team uses stable diffs. Lint again before you commit.
A designer exports minified YAML, and reviewers cannot spot accidental path renames.
Format for readability
Paste into format-openapi, pick a 2-space indent, and enable sort keys if the team agrees.
Validate, then lint
Validate with Scalar, then lint for paths-kebab-case and operation-success-response on new endpoints.
Document the error responses
Lint enforces the presence of a 2xx response. Add 4xx and 5xx responses with descriptions by hand for production-grade contracts, since v1 lint errors do not cover them.
PR review workflow, from design-first to merge
Treat the browser trio as a fast gate before git push. CI remains the team's source of truth, but catching issues locally saves pipeline minutes. Run validate-openapi to fix Scalar errors, then format-openapi for a readable diff. Finish with lint-openapi to resolve errors and then warnings per team policy, and commit.
Beyond a green validate, ask whether operationId values are unique and stable for codegen. Ask whether tags map to your API portal navigation, and whether every operation documents at least one success response. Ask too whether common error shapes are described for client teams.
In CI, teams often run Spectral, openapi-cli, or Redocly with custom rulesets stricter than FastMinify v1. Combine browser lint with our CI/CD automation guide. For schema pivots, use json-schema-to-openapi and openapi-to-json-schema on the hub. To validate payloads against a schema once the contract is sound: see our JSON Schema validation guide.
Conclusion
Maintainable OpenAPI specs need more than schema validation. Lint catches the operationId, tag, and response gaps that block generators, and formatting keeps PRs reviewable. Validate first, format for humans, and lint for style, all locally before CI. Explore the API hub for JSON Schema conversion and GraphQL SDL validation when your contract work expands beyond REST.
Lint and format your OpenAPI spec now
Related Articles

Paste a token and a JWKS to check an RS256, ES256 or HS256 signature in your browser. How kid picks the key, measured errors and the claims to check.

HTTP/2 and HTTP/3 change how files travel, not how big they are. Measured sizes, compile times and bundling tests show what minification still saves.

Convert a Unix epoch to a readable date and back, tell seconds from milliseconds, and avoid time zone, JWT and clock change traps, all in your browser.