Tool overview
OpenAPI 검증기이란?
OpenAPI 검증기은(는) OpenAPI 및 Swagger 문서를 오류, 경고, 경로 커버리지와 함께 lint 위한 개발자 도구입니다.
왜 OpenAPI 검증기을(를) 사용하나요?
OpenAPI 및 Swagger 문서를 오류, 경고, 경로 커버리지와 함께 lint할 때 가독성과 작업 속도를 높이며 서버로 데이터를 보내지 않습니다.
주요 기능
클라이언트 사이드 프라이버시, 즉시 결과, 원클릭 복사. OpenAPI 및 Swagger 문서를 오류, 경고, 경로 커버리지와 함께 lint
사용 방법
위 도구에서 정확한 결과를 얻기 위한 단계입니다.
- Paste OpenAPI 3또는Swagger 2 JSON/YAML.
- Review status: VALID, VALID WITH WARNINGS,또는INVALID.
- Fix errors및pipe cleaned spec into Kiota SDK Engine.
Validation Checks
이 유틸리티의 유효한 예시, 흔한 잘못된 입력, 자주 발생하는 오류를 확인하세요.
Version field
Requires openapi또는swagger version key.
Paths object
Every API must declare at least one path template.
Servers warning
Missing servers[] may require client base URL overrides.
Use case: CI / PR lint gate
Pull requests merge OpenAPI edits that later break nightly SDK regeneration. Reviewers cannot spot duplicate operationIds by eye.
How this tool solves it
- Paste the PR’s OpenAPI document into the validator during review.
- Require VALID (or documented warnings only) before approve.
- Call out duplicate operationId and broken $ref in the review thread with the diagnostic text.
- 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.
Use case: pre-SDK check before Kiota
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
- Lint the document here until INVALID is cleared.
- Pipe into Kiota SDK Engine and review the OpenAPI Readiness score.
- Fix any remaining Kiota-specific issues (circular refs, nullable style) in the Kiota diagnostics.
- Copy the generated CLI command once readiness is acceptable.
A two-step local workflow: structural lint → Kiota readiness → generate on your machine.
Use case: Swagger 2 migration warnings
An older Swagger 2 JSON still powers a gateway. Stakeholders want OpenAPI 3 before adopting Kiota.
How this tool solves it
- Paste the Swagger 2 document and note migration warnings.
- Fix structural INVALID issues that would block any converter.
- Plan an OpenAPI 3 migration for new features; keep Swagger 2 only while gated.
- Re-lint the OpenAPI 3 result before Kiota.
Clear signal that Swagger 2 is parsed with warnings — prefer OpenAPI 3 for new SDK work.
Fix: duplicate operationId
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
- Assign a unique operationId to every operation (verb + resource is a common pattern).
- Remove unused duplicate paths that were copied during editing.
- 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.
Fix: missing or empty responses
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
- Add at least one success response with an application/json (or relevant) media type.
- Point content schema to components.schemas via $ref instead of leaving content empty.
- Document error responses (4xx/5xx) when clients must handle them — warnings may remain if omitted.
Fix: invalid or dangling $ref
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
- Repair or recreate the missing component target.
- Normalize $ref strings to #/components/... pointers.
- Break circular references by extracting shallow DTOs (Kiota’s circular-ref guide applies next).
VALID vs VALID WITH WARNINGS vs INVALID
Interpret the banner before you change the document.
Validation status
| Status | Meaning | Next step |
|---|---|---|
| VALID | No blocking structural issues detected | Safe to pipe into Kiota or commit |
| VALID WITH WARNINGS | Parses but has non-blocking issues (e.g. servers, Swagger 2) | Review warnings; proceed if acceptable |
| INVALID | Blocking errors present | Fix diagnostics before codegen |
Pipe cleaned specs into Kiota SDK Engine
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.
OpenAPI lint best practices
- 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.
자주 묻는 질문
일반적인 문제와 데이터 프라이버시에 대한 답변입니다.
관련 도구
이 도구를 보완하는 관련 유틸리티를 살펴보세요.
공식 문서 및 참고 자료
이 유틸리티의 공식 사양 및 플랫폼 문서입니다.