OpenAPI 뷰어는 3,000줄짜리 openapi.yaml을 받았는데 이 API가 무엇을 제공하는지만 빨리 알고 싶을 때 쓰는 도구입니다. YAML이나 JSON을 붙여 넣으면 OpenAPI 버전, API 제목과 버전, 서버 URL, 그리고 지원하는 오퍼레이션의 HTTP 메서드, 경로, 요약, operationId, 준비됨·검토 상태를 목록으로 보여 줍니다. 같은 문서 안의 $ref 경로 항목을 따라가고 3.1·3.2 웹훅도 나열합니다.
이 목록은 Swagger UI처럼 훑어보는 용도가 아니라 검토용입니다. operationId가 없거나 중복이거나, OpenAPI 3.0에서 필수인 responses가 없거나, 경로의 {name}에 맞는 경로 파라미터가 없는 오퍼레이션에 상태 표시가 붙습니다. OpenAPI 3.1과 3.2에서 responses가 없으면 참고만 표시합니다. 텍스트와 메서드로 필터링하고, 태그로 묶고, 행을 펼쳐 태그·응답·설명을 볼 수 있습니다.
문서는 브라우저 안에서 해석됩니다. 사양 문서는 내부 API를 다루는 경우가 많으므로 아무것도 업로드하지 않으며, 파일에 적힌 서버를 호출하지도 않습니다.
사용 방법
문서 붙여 넣기
OpenAPI 3.0.x, 3.1.x 또는 3.2.x 문서를 YAML이나 JSON으로 붙여 넣거나(JSON도 유효한 YAML이라 동작합니다) 파일을 편집기에 끌어다 놓습니다. 2 MiB까지 받으며, 샘플로 Books API, 참조와 웹훅이 있는 3.1 문서, 검토가 필요한 문서를 불러올 수 있습니다.
요약 읽기
머리글에 API 제목·버전과 OpenAPI 버전이 나오고, 카운터가 오퍼레이션 수, operationId가 있는 수, 서버 수, 검토가 필요한 수를 알려 줍니다. 서버 URL은 그 아래에 나열됩니다.
엔드포인트 필터링과 묶기
필터 입력란에 입력하면 경로, 요약, 오퍼레이션 ID, 설명, 태그에서 찾고, 메서드 버튼으로 일부 메서드만 남기거나 태그별로 묶을 수 있습니다. 행은 문서에 나온 순서입니다.
행을 펼치고 검토 표시된 것 고치기
행을 누르면 오퍼레이션 ID, 태그, 응답, 설명이 보입니다. 검토로 표시된 행은
operationId가 없거나 중복이거나 OpenAPI 3.0에서responses가 없거나, 경로 파라미터가 선언되지 않았거나 required가 아닌 것입니다. 3.1과 3.2에서responses가 없으면 참고만 표시합니다.엔드포인트 목록 복사
엔드포인트 목록 탭으로 바꿔
METHOD /path: operationId줄을 복사해 팀에 공유하거나 리뷰 댓글에 붙여 넣으세요.
작동 원리
OpenAPI 문서에서 오퍼레이션이 있는 곳
OpenAPI 명세(spec.openapis.org)는 HTTP API를 openapi(버전 문자열), info, 선택적 servers, API 구조가 있는 루트 객체로 기술합니다. OpenAPI 3.0은 paths 맵이 필요하지만 3.1과 3.2는 components나 webhooks만 있는 문서도 허용합니다. 이 뷰어는 각 경로 아래에서 3.0과 3.1의 여덟 HTTP 메서드 키를 읽습니다.
Path Item은 문서 안 다른 곳의 정의를 가리키는 $ref일 수도 있습니다. 3.1의 #/components/pathItems/Health가 그 예입니다. 뷰어는 같은 문서 안을 가리키는 참조를 순환을 막으면서 따라갑니다. OpenAPI 3.1은 API가 소비자를 호출하는 오퍼레이션의 webhooks 맵도 허용하며, 이는 웹훅으로 표시해 나열합니다.
| 필드 | 위치 | 뷰어가 보고하는 것 |
|---|---|---|
| openapi | 루트 | 3.0.x, 3.1.x 또는 3.2.x여야 함. 따옴표 없는 3.0도 허용 |
| info.title | 루트 > info | API 이름. 없으면 "Untitled API" |
| info.version | 루트 > info | API 릴리스. 없으면 대시 |
| servers | 루트 | 서버 URL 목록 |
| operationId | 오퍼레이션 | 식별자. 없거나 중복이면 검토 표시 |
| summary | 오퍼레이션 | 요약 텍스트. 없으면 참고 표시 |
| responses | 오퍼레이션 | 응답 코드. 없으면 3.0은 검토, 3.1·3.2는 참고 표시 |
| parameters | 경로 항목, 오퍼레이션 | in: path 항목만 읽음. 경로의 {name}마다 선언되어 있고 required: true여야 함 |
operationId가 중요한 이유
명세는 operationId를 도구와 라이브러리를 위한, 오퍼레이션을 식별하는 고유한 문자열로 정의합니다. 코드 생성기는 이를 메서드 이름(listPets())으로, API 게이트웨이는 라우팅 규칙으로, 문서 도구는 앵커로 씁니다. 없으면 생성기가 경로와 메서드로 이름을 지어내는데 경로가 바뀔 때마다 이름이 바뀌고, 두 오퍼레이션이 같은 ID를 쓰면 대부분의 생성기가 실패하거나 하나의 이름을 조용히 바꿉니다. 그래서 없거나 중복된 ID를 표시하는 것은 클라이언트를 생성할 사양에 가장 유용한 단일 점검입니다.
operationId가 없거나 중복이거나, OpenAPI 3.0 오퍼레이션에 responses가 없거나, 경로 파라미터에 오류가 있으면 검토 상태입니다. OpenAPI 3.1과 3.2에서는 responses가 선택 사항이므로 없을 때 참고만 표시합니다. 경로 파라미터 오류란 경로의 {name}에 대응하는 in: path 파라미터가 선언되지 않았거나, 경로 파라미터에 required: true가 없는 경우입니다.
뷰어가 일부러 건너뛰는 것
다른 파일에 대한 참조($ref: './paths/pets.yaml')는 붙여 넣은 내용만 볼 수 있으므로 불러오지 않으며, 그런 경로 항목은 건너뜀으로 나열합니다. OpenAPI 2.0(Swagger)은 거부합니다. OpenAPI 3.2는 3.1처럼 읽지만 3.2 전용 query 메서드와 additionalOperations는 검사하거나 나열하지 않습니다.
실제 예시
openapi: 3.0.3
info:
title: Pet Store
version: 2.1.0
servers:
- url: https://api.example.com/v2
- url: https://staging.example.com/v2
paths:
/pets:
get:
operationId: listPets
summary: List pets
responses:
'200': {description: ok}
post:
operationId: createPet
responses:
'201': {description: created}
/pets/{petId}:
parameters:
- {name: petId, in: path, required: true}
get:
summary: Get one pet
responses:
'200': {description: ok}
delete:
operationId: deletePet
summary: Remove a pet
responses:
'204': {description: gone}
/health:
head: {}OpenAPI 3.0.3 | Pet Store | 버전 2.1.0 | 서버 2개
GET /pets listPets List pets 준비됨
POST /pets createPet (요약 없음) 준비됨
GET /pets/{petId} - Get one pet 검토: operationId를 추가하세요. 코드 생성기와 API 클라이언트가 메서드 이름으로 사용합니다.
DELETE /pets/{petId} deletePet Remove a pet 준비됨
HEAD /health - (요약 없음) 검토: operationId를 추가하세요. 코드 생성기와 API 클라이언트가 메서드 이름으로 사용합니다.; responses는 필수입니다. 응답을 하나 이상 설명하세요.도구의 파서를 직접 실행한 결과입니다. 오퍼레이션 두 개가 검토로 표시됩니다.
openapi: 3.1.0
info: {title: Billing API, version: 2.3.0}
paths:
/health:
$ref: "#/components/pathItems/Health"
webhooks:
invoicePaid:
post:
operationId: onInvoicePaid
responses:
"200": {description: ok}
components:
pathItems:
Health:
get:
operationId: health
responses:
"200": {description: ok}GET /health health 준비됨
POST invoicePaid onInvoicePaid 준비됨 (웹훅)health 오퍼레이션은 참조된 컴포넌트에서 가져오고, 웹훅은 웹훅 배지와 함께 나열됩니다.
openapi: 3.0.3
info: {title: T, version: '1'}
paths:
/users:
get:
operationId: users
responses: {'200': {description: ok}}
post:
operationId: users
responses: {'201': {description: ok}}GET /users users 검토: 이 operationId가 여러 번 쓰였습니다. 문서 안에서 고유해야 합니다.
POST /users users 검토: 이 operationId가 여러 번 쓰였습니다. 문서 안에서 고유해야 합니다.어느 쪽이 실수인지 알 수 없으므로 두 행 모두 표시합니다.
openapi: 3.0
info: {title: T, version: '1'}
paths: {}OpenAPI 3.0 | T | 버전 1 | 오퍼레이션 0개YAML은 따옴표 없는 3.0을 숫자 3으로 읽습니다. 뷰어는 파일을 거부하지 않고 "3.0"으로 복원합니다.
swagger: '2.0'
paths: {}OpenAPI 3.0, 3.1, 3.2만 지원합니다. Swagger 2.0 파일은 먼저 OpenAPI 3.x로 변환하세요.Swagger 2.0에 표시되는 버전 오류입니다. OpenAPI 3.x로 변환한 뒤 붙여 넣으세요.
자주 하는 실수
뷰어를 검증기로 착각
"준비됨" 행은 operationId가 있고 고유하며 버전별 응답 규칙과 기본 경로 파라미터 검사를 통과했다는 뜻입니다. 따라서 OpenAPI 3.1·3.2 오퍼레이션은 응답 없이도 준비됨일 수 있습니다. 잘못된 스키마와 깨진 스키마
$ref는 검사하지 않습니다.여러 파일로 나뉜 사양이 펼쳐질 것이라 기대
$ref: './paths/pets.yaml'같은 다른 파일 참조는 붙여 넣은 내용만 볼 수 있어 불러오지 않으며 해당 경로는 건너뜀으로 나열됩니다. 먼저 사양을 하나의 파일로 번들링하세요.중복된 operationId를 넘어감
같은 ID를 쓰는 두 오퍼레이션은 각각은 멀쩡해 보여도 많은 생성기를 깨뜨립니다. 뷰어가 중복을 모두 표시하므로 생성기가 승자를 고르게 두지 말고 직접 고치세요.
웹훅을 놓침
웹훅은 클라이언트가 요청하는 경로가 아니라 내 API가 다른 곳을 호출하는 것입니다. 웹훅 배지와 함께 나열되므로 클라이언트가 호출할 수 있는 엔드포인트로 읽지 마세요.
숫자로 쓴 버전 문자열
YAML에서
openapi: 3.0은 숫자로 해석됩니다. 뷰어는 받아들이지만 다른 도구는 그렇지 않을 수 있으니3.0.3전체를 쓰거나 따옴표로 감싸세요.
자주 묻는 질문
어떤 OpenAPI 버전을 지원하나요?
OpenAPI 3.0.x, 3.1.x, 3.2.x입니다. 3.2는 3.1처럼 읽으므로 3.2 전용 query와 additionalOperations는 검사하거나 나열하지 않습니다. Swagger 2.0은 거부합니다.
YAML 대신 JSON을 붙여 넣어도 되나요?
예. 입력을 YAML로 해석하는데 JSON은 유효한 YAML이므로 두 형식 모두 동작합니다.
검토 상태는 무슨 뜻인가요?
오퍼레이션에 operationId가 없거나 다른 오퍼레이션과 같거나 OpenAPI 3.0에서 responses가 없거나, 경로 템플릿의 이름에 맞는 필수 in: path 파라미터가 없다는 뜻입니다. OpenAPI 3.1과 3.2에서 responses가 없으면 참고만 표시합니다.
내 사양에 적힌 서버로 요청을 보내나요?
아니요. 어떤 URL도 호출하지 않습니다. 문서는 브라우저 안에서 해석되며 업로드되지 않습니다.
$ref를 따라가고 웹훅도 나열하나요?
#/components/pathItems/Health처럼 같은 문서 안을 가리키는 $ref 경로 항목은 따라가고 3.1 웹훅도 나열합니다. 다른 파일에 대한 참조는 건너뜀으로 보고합니다.
크기 제한이 있나요?
예, 텍스트 2 MiB입니다. 더 큰 사양은 검토할 엔드포인트만 남기거나 번들링하세요.
왜 어떤 엔드포인트가 목록에 없나요?
경로 바로 아래나 참조된 경로 항목 안에 적힌 메서드만 나열합니다. 다른 파일을 가리키는 $ref 경로나 표준 여덟 가지 밖의 메서드 이름은 포함되지 않습니다.
더 깊이 읽기
마지막 업데이트: