이 페이지는 DevUtilities로 브라우저에서 OpenAPI 및 Swagger 문서를 lint하는 표준 가이드입니다. 읽는 동안 위에 스펙을 붙여넣거나 아래 주제로 이동하세요. 검증은 로컬에 유지되며 문서는 업로드되지 않습니다. lint가 초록이면 Kiota SDK Engine으로 파이프하여 준비 점수와 generate 명령 미리보기를 확인하세요.

OpenAPI Validator는 OpenAPI 3 및 Swagger 2 JSON/YAML용 클라이언트 측 린터입니다. VALID, VALID WITH WARNINGS 또는 INVALID를 경로 인식 진단과 함께 보고하여 SDK 생성이나 게이트웨이 가져오기 전에 차단 항목을 고칠 수 있습니다.

얻는 것

• OpenAPI 3.x 및 Swagger 2 문서(JSON 또는 YAML) 파싱
• 상태 배너: VALID / VALID WITH WARNINGS / INVALID
• 버전 키, paths 커버리지, servers 및 일반 구조 문제 검사
• 로컬 전용 lint — 내부 API 스펙에 안전
• codegen 준비를 위한 Kiota SDK Engine으로의 직접 전달

다음일 때 이 도구를 사용

• Microsoft Kiota 또는 다른 생성기 전 빠른 사전 점검이 필요할 때
• CI 또는 PR 체크리스트가 커밋된 스펙의 읽기 쉬운 lint를 요구할 때
• Swagger 2 파일을 물려받아 OpenAPI 3 작업 전 마이그레이션 경고가 필요할 때
• 중복 operationId 또는 깨진 $ref가 codegen을 계속 깨뜨릴 때

다음일 때 관련 도구를 선호

• 전체 Kiota 준비 점수, 언어 매트릭스, CLI 빌더가 필요 → Kiota SDK Engine
• JSON 페이로드 미화가만 필요 → JSON Formatter
• 모의 응답 배열이 필요 → JSON Generator

코드 생성기(특히 Kiota)는 대충 YAML을 훑어봐서는 놓치는 구조 문제로 크게 실패합니다. 먼저 여기서 lint한 뒤 Kiota SDK Engine에서 생성기별 준비를 확인하세요.

codegen 전에 지울 차단 항목

• 중복 또는 누락된 operationId(메서드 이름 충돌)
• 성공 상태 코드의 누락되거나 비어 있는 responses
• components로의 잘못되었거나 끊긴 $ref
• openapi/swagger 버전 키 누락 또는 빈 paths 객체
• 순환 schema 참조(대개 다음에 Kiota에서 드러남)

미룰 수 있는 경고

• servers[] 누락 — 클라이언트에 --base-url 재정의가 필요할 수 있음
• Swagger 2 마이그레이션 메모 — 새 API는 OpenAPI 3 선호
• 빈약한 설명 — 문서 품질이지 파싱 차단 항목은 아님

SDK 생성 전 첫 안내.

1. 입력 패널에 OpenAPI 3 또는 Swagger 2를 JSON/YAML로 붙여넣습니다.
2. 상태를 읽습니다: VALID, VALID WITH WARNINGS 또는 INVALID.
3. 진단 목록의 모든 오류를 수정 — operationId, responses, $ref 실패부터 시작합니다.
4. VALID가 되거나 허용 가능한 경고만 남을 때까지 다시 lint합니다.
5. 정리된 스펙을 Kiota SDK Engine으로 파이프하여 점수, 언어 미리보기, kiota generate 명령을 확인합니다.
6. 수정한 문서를 커밋하고 선택적으로 이 lint를 PR 체크리스트 항목으로 추가합니다.

풀 리퀘스트가 OpenAPI 편집을 병합한 뒤 야간 SDK 재생성을 깨뜨립니다. 검토자는 중복 operationId를 눈으로 찾기 어렵습니다.

이 도구가 해결하는 방법

1. 검토 중 PR의 OpenAPI 문서를 검증기에 붙여넣습니다.
2. 승인 전에 VALID(또는 문서화된 경고만)를 요구합니다.
3. 진단 텍스트와 함께 중복 operationId와 깨진 $ref를 검토 스레드에 지적합니다.
4. 병합 후 동일 문서에 대해 CI에서 Kiota를 실행합니다.

생성기가 맞닥뜨리는 것과 같은 실패 유형을 잡는 사람 속도 lint 게이트 — 스펙은 업로드하지 않습니다.

팀이 kiota generate를 실행하려 하며 이름 지정이나 $ref 문제로 실패하지 않을 확신이 필요합니다.

이 도구가 해결하는 방법

1. INVALID가 없어질 때까지 여기서 lint합니다.
2. Kiota SDK Engine으로 파이프하고 OpenAPI Readiness 점수를 검토합니다.
3. 남은 Kiota 전용 문제(순환 참조, nullable 스타일)를 Kiota 진단에서 수정합니다.
4. 준비가 충분하면 생성된 CLI 명령을 복사합니다.

로컬 2단계 워크플로: 구조 lint → Kiota 준비 → 내 기기에서 generate.

오래된 Swagger 2 JSON이 여전히 게이트웨이를 구동합니다. 이해관계자는 Kiota 채택 전 OpenAPI 3를 원합니다.

이 도구가 해결하는 방법

1. Swagger 2 문서를 붙여넣고 마이그레이션 경고를 기록합니다.
2. 어떤 변환기도 막을 구조 INVALID 문제를 수정합니다.
3. 새 기능을 위해 OpenAPI 3 마이그레이션을 계획하고, 게이트된 동안만 Swagger 2를 유지합니다.
4. Kiota 전에 OpenAPI 3 결과를 다시 lint합니다.

Swagger 2는 경고와 함께 파싱된다는 명확한 신호 — 새 SDK 작업에는 OpenAPI 3를 선호하세요.

생성기는 operationId로 클라이언트 메서드 이름을 정합니다. 중복은 충돌을 일으킵니다.

발생 이유

둘 이상의 작업이 같은 operationId를 공유하거나, 생성기가 요구하는 곳에 operationId가 없습니다.

진단

문서에서 반복된 operationId 값을 검색합니다. Kiota와 이 린터 모두 충돌을 표시합니다 — SDK 엔진을 열기 전에 여기서 고치세요.

수정

1. 모든 작업에 고유 operationId를 부여합니다(동사 + 리소스가 흔한 패턴).
2. 편집 중 복사된 사용하지 않는 중복 paths를 제거합니다.
3. 부분 SDK용으로 줄일 때는 프로덕션 ID를 함부로 바꾸지 말고 충돌 paths를 제거합니다.

이름 변경 후 다시 lint하고 Kiota 준비를 재확인하세요 — 미리보기의 메서드 이름이 바뀝니다.

사용 가능한 responses가 없는 작업은 타입이 있는 클라이언트 생성을 깨뜨립니다.

발생 이유

path 작업이 responses를 생략하거나, 성공 responses가 schema 없는 빈 content {}를 가집니다.

진단

각 작업의 responses 맵에서 200/201(또는 default) 항목을 검사하고 content schema가 해석되는지 확인합니다.

수정

1. application/json(또는 관련) 미디어 타입이 있는 성공 response를 하나 이상 추가합니다.
2. content를 비워 두지 말고 $ref로 components.schemas를 가리킵니다.
3. 클라이언트가 처리해야 하면 오류 responses(4xx/5xx)를 문서화 — 생략 시 경고가 남을 수 있습니다.

잘못된 $ref 포인터는 lint와 codegen 중 schema 해석을 막습니다.

발생 이유

$ref가 없는 컴포넌트를 가리키거나, 잘못된 JSON Pointer를 쓰거나, 해석기가 펼칠 수 없는 순환을 만듭니다.

진단

실패한 각 $ref 경로를 components.schemas / parameters / responses까지 따라가 대상 키가 존재하고 철자가 일치하는지 확인합니다.

수정

1. 누락된 컴포넌트 대상을 수리하거나 다시 만듭니다.
2. $ref 문자열을 #/components/... 포인터로 정규화합니다.
3. 얕은 DTO를 추출해 순환 참조를 끊습니다(다음에 Kiota 순환 참조 가이드가 적용됩니다).

문서를 바꾸기 전에 배너를 해석하세요.

OpenAPI Validator와 Kiota SDK Engine은 보완적입니다. 여기서 구조 건강을 lint하고, Kiota로 생성기 준비, 언어 매트릭스, 엔드포인트 선택, CLI 명령 내보내기를 수행하세요.

• VALID 이후 정리된 스펙을 Kiota SDK Engine에 파이프하거나 붙여넣습니다.
• 중복 operationId, 순환 $ref, nullable 스타일 등 생성기가 강조하는 문제는 Kiota 진단을 사용합니다.
• Kiota Generate 단계에서 kiota generate를 복사 — 파일 출력은 여전히 로컬 Kiota CLI로 실행됩니다.
• 두 도구를 클라이언트 측에 유지해 내부 API 계약이 브라우저를 떠나지 않게 합니다.

• 승인 전 모든 OpenAPI PR에서 lint합니다.
• 새 API는 OpenAPI 3를 선호하고 Swagger 2는 마이그레이션 경고가 있는 레거시로 취급합니다.
• operationId를 고유하고 안정적으로 — 이름 변경은 생성된 클라이언트를 흔듭니다.
• 성공 responses에는 항상 해석 가능한 schema를 제공합니다.
• Kiota를 열기 전에 INVALID를 제거하고, 생성기별 준비는 다음에 Kiota로.
• 이 로컬 경로로 충분하면 내부 스펙을 타사 lint SaaS에 업로드하지 마세요.