OpenAPI 3.0 YAML 빌더 사용 가이드
OpenAPI 3.0(구 Swagger) 명세는 REST API를 기계가 읽을 수 있는 형태로 기술하는 산업 표준입니다. 잘 작성된 OpenAPI 문서 하나만 있으면 Swagger UI·Redoc 같은 문서 사이트가 자동 생성되고, openapi-generator로 클라이언트 SDK·Mock 서버·테스트 코드까지 만들 수 있습니다. 그러나 YAML 들여쓰기 두 칸 차이로 파싱이 깨지거나, parameters의 in 값이 path인데 required:true 빠뜨려서 검증 오류가 나는 일이 빈번합니다. 이 도구는 폼 입력만으로 안전한 OpenAPI 3.0 명세를 생성합니다.
먼저 상단에 API 제목·버전·서버 URL을 입력합니다. 그런 다음 "+ 엔드포인트 추가" 버튼으로 path와 HTTP 메서드를 정의하고, 각 path 내부에서 parameters(query / path / header), requestBody(application/json 스키마), responses(상태코드별 응답)을 채워 넣습니다. 컴포넌트 스키마 영역에는 재사용 가능한 객체 스키마를 정의해 두면 $ref: '#/components/schemas/Name' 형태로 자동 참조됩니다.
OpenAPI 작성 시 자주 하는 실수
1) path 파라미터를 URL에 {id}로 적었는데 parameters에 in: path 항목을 빠뜨리는 경우 — 검증이 실패합니다. 2) responses 키에 default 없이 200만 적어 두면 4xx·5xx 케이스가 문서에 보이지 않아 클라이언트 개발자가 에러 처리를 못합니다. 3) requestBody에 required 명시를 깜빡하면 일부 코드 생성기가 nullable 처리하여 타입이 어긋납니다. 이 빌더는 path 패턴에서 {param}을 자동 인식해 parameters에 추가하고, required 기본값을 path는 true, query는 false로 설정합니다.
자주 묻는 질문 (FAQ)
Q. YAML과 JSON 중 어느 쪽을 쓰는 게 좋은가요?
A. 사람이 읽고 편집할 때는 YAML이 압도적으로 편하고, CI/CD나 다른 도구가 자동으로 처리할 때는 JSON이 더 안전합니다. 둘은 100% 1:1 변환되므로 한쪽만 정본으로 관리하면 됩니다.
Q. Swagger UI에서 어떻게 띄울 수 있나요?
A. 생성된 YAML을 openapi.yaml로 저장한 뒤, swagger-ui의 url 옵션에 해당 파일 경로를 지정하거나 npx swagger-ui-watcher openapi.yaml 같은 명령으로 즉시 미리보기를 띄울 수 있습니다.
Q. 인증·OAuth는 어떻게 추가하나요?
A. components.securitySchemes에 bearerAuth 또는 OAuth2 흐름을 정의한 뒤, 각 path 또는 전역 security 키에서 참조합니다. 본 빌더는 기본 베어러 토큰 보안 스킴을 자동 포함합니다.