이 OpenAPI 뷰어 및 검증기는 YAML 또는 JSON으로 된 OpenAPI 3.0, 3.1, Swagger 2.0 문서를 읽어 탐색 가능한 API 문서로 보여 줍니다. 모든 엔드포인트가 태그별로 묶이고 파라미터, 요청 본문, 응답, 스키마와 바로 실행할 수 있는 cURL 명령이 함께 표시됩니다. 명세를 붙여 넣거나 파일을 여세요. 아무것도 업로드되지 않으므로 내부 API나 공개 전 API도 비공개로 유지됩니다.
검증기는 명세서에서 가져온 23가지 구조 검사를 실행하며, 각 검사는 페이지에 나열되어 있습니다. info와 paths 존재 여부, 설명과 올바른 상태 코드를 갖춘 응답, 경로의 모든 {parameter}가 필수 경로 파라미터로 선언되었는지, 고유한 operationId, 해석되는 $ref, 정의된 스킴을 가리키는 보안 요구 사항 등입니다. 이는 코드 생성기와 문서 도구를 망가뜨리는 오류들입니다. 명세의 공식 JSON Schema에 대한 완전한 검증은 아니므로, 여기서 통과한 명세에도 예를 들어 철자가 틀린 스키마 키워드가 있을 수 있습니다. 다른 파일을 가리키는 외부 $ref는 목록에만 표시하고 가져오지 않습니다.
사용 방법
- openapi.yaml, openapi.json 또는 swagger.json을 붙여 넣거나 파일을 엽니다. 처음에는 예제 API가 불러와져 있습니다.
- 상태 줄과 검증 목록을 확인합니다. 각 문제에는 규칙과 위치(예: paths./pets/{id}.get)가 표시됩니다.
- 문서를 살펴봅니다. 작업은 태그별로 묶여 있으며, 하나를 클릭하면 파라미터, 요청 본문, 응답, 스키마가 보입니다.
- 경로, 요약 또는 operationId로 필터링해 대용량 명세에서 엔드포인트를 찾습니다.
- 작업의 cURL 예제를 복사하고 <TOKEN> 또는 <API_KEY> 자리 표시자를 내 자격 증명으로 바꿉니다.
자주 묻는 질문
Swagger나 OpenAPI 파일은 어떻게 보나요?
YAML 또는 JSON을 상자에 붙여 넣거나 파일을 여세요. 뷰어가 버전(swagger: "2.0" 또는 openapi: 3.0.x / 3.1.x)을 감지하고, 엔드포인트를 태그별로 나열하며, 각각을 펼쳐 파라미터, 요청 본문, 응답, 해석된 스키마를 볼 수 있게 합니다. 페이지를 한 번 불러오면 오프라인에서도 작동합니다.
OpenAPI 검증기는 무엇을 검사하나요?
명세서의 구조 규칙입니다: 지원되는 버전 필드, title과 version이 있는 info, /로 시작하는 경로, 설명과 올바른 상태 코드가 있는 비어 있지 않은 responses를 갖춘 작업, 선언되고 필수인 경로 템플릿 파라미터, name과 올바른 in, schema를 갖춘 파라미터, 중복 없는 파라미터와 operationId, content가 있는 요청 본문, 해석되는 $ref, 정의된 스킴을 가리키는 보안 요구 사항. 전체 목록은 페이지의 “검사 항목”에 있습니다. 모든 스키마 키워드를 공식 JSON Schema에 대해 검증하지는 않습니다.
선언하지 않은 경로 파라미터가 왜 오류인가요?
명세서는 경로 템플릿의 모든 {name}에 대해 경로 또는 작업 수준에서 in: path와 required: true를 가진 파라미터가 있어야 한다고 규정합니다. 문서를 JSON Schema로만 검사하는 일부 검증기는 누락을 허용하지만, 그러면 코드 생성기는 해당 인자가 없는 함수를 만들고, 문서 도구는 올바르게 호출할 수 없는 엔드포인트를 보여 줍니다.
OpenAPI 3.1과 Swagger 2.0도 읽을 수 있나요?
네. Swagger 2.0의 body와 formData 파라미터는 요청 본문으로, produces와 consumes는 미디어 타입으로 표시되므로 세 버전 모두 같은 방식으로 읽힙니다. OpenAPI 3.1의 차이도 반영합니다. components나 webhooks가 있으면 paths는 선택 사항이고, responses는 선택 사항이며(여기서는 경고), type: [string, "null"]은 nullable로 표시됩니다.
외부 $ref 파일도 불러오나요?
아니요. 다른 파일이나 URL을 가리키는 $ref(예: ./schemas/user.yaml)는 경고로 나열되고 해석되지 않은 것으로 표시됩니다. 페이지는 직접 열지 않은 파일을 읽을 수 없고 스스로 URL을 가져오지 않기 때문입니다. 여러 파일로 된 명세는 먼저 redocly bundle이나 swagger-cli bundle 등으로 하나의 문서로 묶으세요.
API 명세가 업로드되나요?
아니요. 파싱, 검증, 렌더링은 모두 브라우저에서 실행됩니다. 명세는 어디로도 전송되지 않습니다.
OpenAPI 3.x와 Swagger 2.0: 달라진 점
• 버전 필드: swagger: "2.0"이 openapi: 3.0.x, 이어서 3.1.x가 되었습니다.
• 서버: 2.0에는 host, basePath, schemes가 있고, 3.x에는 변수를 포함하는 servers 목록이 있습니다.
• 요청 본문: 2.0은 in: body(또는 formData) 파라미터를 쓰고, 3.x는 미디어 타입별 content가 있는 requestBody를 씁니다.
• 재사용 요소: 2.0은 최상위에 definitions, parameters, responses를 두고, 3.x는 이를 securitySchemes, requestBodies, examples와 함께 components 아래에 둡니다.
• 3.1은 스키마를 JSON Schema 2020-12에 맞춥니다. type이 목록일 수 있고(nullable: true 대신 ["string", "null"]), examples는 배열이며, webhooks가 추가되었습니다.
API 도구를 가장 자주 망가뜨리는 오류
• 선언되지 않았거나 required: true 없이 선언된 경로 파라미터.
• 오타가 있는 $ref(schemas 대신 #/components/schema/User). 문서 일부가 비게 됩니다.
• 중복된 operationId. 코드 생성기가 실패하거나 메서드를 덮어씁니다.
• description이 없는 응답(그냥 "OK"라도 필수입니다).
• 정의되지 않은 스킴을 가리키는 보안 요구 사항. 생성된 클라이언트가 인증할 방법이 없어집니다.
