OpenAPI Validator is a client-side linter for OpenAPI 3 and Swagger 2 JSON/YAML. It reports VALID, VALID WITH WARNINGS, or INVALID with path-aware diagnostics so you can fix blockers before SDK generation or gateway import.

What you get

• Parse OpenAPI 3.x and Swagger 2 documents (JSON or YAML)
• Status banner: VALID / VALID WITH WARNINGS / INVALID
• Checks for version keys, paths coverage, servers, and common structural issues
• Local-only lint — safe for internal API specs
• Direct handoff path to Kiota SDK Engine for codegen readiness

Use this tool when

• You need a fast pre-flight before Microsoft Kiota or other generators
• CI or a PR checklist requires a human-readable lint of the committed spec
• You inherited a Swagger 2 file and want migration warnings before OpenAPI 3 work
• Duplicate operationId or broken $ref keep breaking codegen

Prefer a sibling tool when

• You need full Kiota readiness scoring, language matrix, and CLI command builder → Kiota SDK Engine
• You only need to beautify JSON payloads → JSON Formatter
• You need mock response arrays → JSON Generator

Code generators (especially Kiota) fail loudly on structural problems that a casual YAML glance misses. Lint here first, then open Kiota SDK Engine for generator-specific readiness.

Blockers to clear before codegen

• Duplicate or missing operationId (method naming collisions)
• Missing or empty responses on success status codes
• Invalid or dangling $ref into components
• Missing openapi/swagger version key or empty paths object
• Circular schema references (often surface in Kiota next)

Warnings you may defer

• Missing servers[] — clients may need --base-url overrides
• Swagger 2 migration notes — prefer OpenAPI 3 for new APIs
• Sparse descriptions — documentation quality, not parse blockers

First-time walkthrough before generating an SDK.

1. Paste OpenAPI 3 or Swagger 2 as JSON or YAML into the input panel.
2. Read the status: VALID, VALID WITH WARNINGS, or INVALID.
3. Fix every error in the diagnostics list — start with operationId, responses, and $ref failures.
4. Re-lint until the status is VALID or only acceptable warnings remain.
5. Pipe the cleaned spec into Kiota SDK Engine for readiness score, language preview, and kiota generate command.
6. Commit the fixed document and optionally add this lint as a PR checklist item.

Pull requests merge OpenAPI edits that later break nightly SDK regeneration. Reviewers cannot spot duplicate operationIds by eye.

How this tool solves it

1. Paste the PR’s OpenAPI document into the validator during review.
2. Require VALID (or documented warnings only) before approve.
3. Call out duplicate operationId and broken $ref in the review thread with the diagnostic text.
4. After merge, run Kiota in CI against the same document.

Human-speed lint gate that catches the same class of failures generators hit — without uploading the spec.

A team is about to run kiota generate and wants confidence the document will not fail on naming or $ref issues.

How this tool solves it

1. Lint the document here until INVALID is cleared.
2. Pipe into Kiota SDK Engine and review the OpenAPI Readiness score.
3. Fix any remaining Kiota-specific issues (circular refs, nullable style) in the Kiota diagnostics.
4. Copy the generated CLI command once readiness is acceptable.

A two-step local workflow: structural lint → Kiota readiness → generate on your machine.

An older Swagger 2 JSON still powers a gateway. Stakeholders want OpenAPI 3 before adopting Kiota.

How this tool solves it

1. Paste the Swagger 2 document and note migration warnings.
2. Fix structural INVALID issues that would block any converter.
3. Plan an OpenAPI 3 migration for new features; keep Swagger 2 only while gated.
4. Re-lint the OpenAPI 3 result before Kiota.

Clear signal that Swagger 2 is parsed with warnings — prefer OpenAPI 3 for new SDK work.

Generators name client methods from operationId. Duplicates cause collisions.

Why it happens

Two or more operations share the same operationId, or operationId is missing where the generator requires it.

Diagnose

Search the document for repeated operationId values. Kiota and this linter both flag collisions — fix here before opening the SDK engine.

Fixes

1. Assign a unique operationId to every operation (verb + resource is a common pattern).
2. Remove unused duplicate paths that were copied during editing.
3. If trimming for a partial SDK, drop conflicting paths instead of renaming production IDs casually.

After renaming, re-lint and then re-check Kiota readiness — method names in previews will change.

Operations without usable responses break typed client generation.

Why it happens

A path operation omits responses, or success responses have empty content {} with no schema.

Diagnose

Inspect each operation’s responses map for 200/201 (or default) entries and ensure content schemas resolve.

Fixes

1. Add at least one success response with an application/json (or relevant) media type.
2. Point content schema to components.schemas via $ref instead of leaving content empty.
3. Document error responses (4xx/5xx) when clients must handle them — warnings may remain if omitted.

Invalid $ref pointers prevent schema resolution during lint and codegen.

Why it happens

A $ref targets a missing component, uses a wrong JSON Pointer, or forms a cycle the resolver cannot expand.

Diagnose

Follow each failing $ref path into components.schemas / parameters / responses. Confirm the target key exists and spelling matches.

Fixes

1. Repair or recreate the missing component target.
2. Normalize $ref strings to #/components/... pointers.
3. Break circular references by extracting shallow DTOs (Kiota’s circular-ref guide applies next).

Interpret the banner before you change the document.

OpenAPI Validator and Kiota SDK Engine are complementary. Lint for structural health here; use Kiota for generator readiness, language matrix, endpoint selection, and CLI command export.

• Pipe or paste the cleaned spec into Kiota SDK Engine after VALID.
• Use Kiota diagnostics for duplicate operationId, circular $ref, and nullable style issues that generators emphasize.
• Copy kiota generate from the Kiota Generate step — file emission still runs via the local Kiota CLI.
• Keep both tools client-side so internal API contracts never leave the browser.

• Lint on every OpenAPI PR before approving.
• Prefer OpenAPI 3 for new APIs; treat Swagger 2 as legacy with migration warnings.
• Make operationId unique and stable — renames churn generated clients.
• Always give success responses a resolvable schema.
• Clear INVALID before opening Kiota; use Kiota for generator-specific readiness next.
• Do not upload internal specs to third-party lint SaaS when this local path suffices.