OpenAPI 3.0 스펙 빌더 완벽 가이드
OpenAPI(구 Swagger) 3.0.3은 REST API의 인터페이스를 기계가 읽을 수 있도록 표준화한 명세 포맷입니다. 본 도구는 폼 입력만으로 OpenAPI 3.0.3 YAML을 생성하므로, 들여쓰기 오류나 키 누락 같은 흔한 실수를 줄여줍니다. 생성된 YAML은 Swagger UI, Redoc, Stoplight Studio, Postman 등에 그대로 import 할 수 있습니다.
핵심 섹션
- info: title, version, description은 필수에 가깝습니다. version은 SemVer(예: 1.0.0)를 권장합니다.
- servers: 운영/스테이징/개발 환경별로 여러 개 등록할 수 있고, 도구는 단일 URL을 기본 생성합니다.
- paths: 엔드포인트별로 GET/POST/PUT/DELETE 같은 operation을 정의하고, parameters / requestBody / responses 를 가집니다.
- components.schemas: 재사용 가능한 데이터 모델을 정의합니다. $ref 로 paths에서 참조합니다.
- components.securitySchemes: bearerAuth(JWT) 또는 apiKey 인증을 정의하고, 전역 security 블록에서 활성화합니다.
bearerAuth (JWT) 패턴
OpenAPI 3.0에서 JWT 인증은 type: http + scheme: bearer + bearerFormat: JWT 조합으로 표현하며, 본 도구의 기본값입니다. apiKey 방식은 header/query/cookie 위치를 지정해야 하며, 본 도구는 X-API-Key 헤더 방식을 채택했습니다. 보안 스킴은 정의만으로는 동작하지 않고, 전역 security 또는 operation 레벨 security 에서 명시적으로 활성화해야 클라이언트 SDK 생성기와 Swagger UI에 자물쇠 아이콘이 표시됩니다.
경로(paths) 작성 팁
경로 파라미터는 중괄호로 감싸고({id}), parameters 배열에 in: path / required: true / schema 를 함께 정의해야 유효합니다. 쿼리스트링은 in: query 로, 요청 본문은 requestBody.content."application/json".schema 에 $ref 또는 인라인 스키마를 둡니다. 응답은 200/201/400/401/404/500 같은 상태 코드별로 정의하고, content type 별 schema 를 제공해야 합니다. 페이지네이션이 잦은 컬렉션 응답이라면 ListResponse 같은 래퍼 스키마를 만들어 두는 편이 유지보수에 유리합니다.
자주 묻는 질문 (FAQ)
Q. 생성된 YAML을 Swagger UI에서 바로 볼 수 있나요?
A. 네. swagger-ui-dist 또는 Redoc에 import하면 즉시 렌더링됩니다. 다운로드된 openapi.yaml 을 그대로 사용하세요.
Q. OpenAPI 3.1과의 차이는 무엇인가요?
A. 3.1은 JSON Schema 2020-12와 완전 호환되며 nullable 처리, webhooks 지원이 추가됩니다. 현재 가장 호환성이 넓은 버전은 3.0.3이라 본 도구는 3.0.3을 기본 채택했습니다.
Q. 스키마에 required 필드는 어떻게 지정하나요?
A. 본 도구는 필드 표에서 "필수" 체크박스를 켜면 자동으로 required 배열에 포함시켜 출력합니다. type: object 의 properties 와 required 가 동시에 채워집니다.