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.