[기획자 가이드] 스웨거(Swagger) 문맹 탈출! API 명세서 핵심만 읽는 법
[기획자 가이드] 스웨거(Swagger) 문맹 탈출! API 명세서 핵심만 읽는 법
개발자가 슬랙으로 보낸 의문의 URL 하나. 눌렀더니 영어와 코드가 가득한 스웨거(Swagger) 화면이 뜹니다.
그리고 따라오는 한 마디: “여기 API 다 나와 있으니 참고해서 기획해 주세요.”
이때 기획자의 뇌는 잠깐 멈추고, 손은 커피를 찾고, 마음은 “이거… 시험지인가?”가 됩니다.
그런데 스웨거를 ‘조금만’ 읽을 줄 알면, “이 데이터 화면에 그릴 수 있나요?” 같은 질문을 매번 던질 필요가 줄어듭니다. 오늘은 복잡한 화면 속에서 기획자가 꼭 확인해야 할 3가지 핵심만, 실무에서 바로 써먹는 순서로 정리합니다.
1) 스웨거(Swagger)가 대체 뭔가요?
스웨거(대개 Swagger UI 화면을 의미)는 서버 개발자가 만든 API 설명서입니다. 화면(프론트엔드)에서 서버에 데이터를 달라고 요청할 때, 어떤 주소로, 어떤 형식으로, 무슨 값을 넣어서 호출해야 하는지 적어둔 약속이죠.
기획자 관점에서는 “우리 서비스가 제공할 수 있는 재료 리스트”에 가깝습니다. 재료가 없는 요리는 만들기 어렵고, 재료가 있으면 조리법(화면 설계)도 현실적으로 잡힙니다.
기획 포인트 “화면에 뭘 그릴지”를 결정할 때, 스웨거는 ‘가능/불가능’을 미리 판별해 주는 레이더입니다. 레이더가 있으면 밤길에 발을 덜 찧습니다. (발가락은 소중합니다) 🦶
2) 기획자가 봐야 할 ‘3대 핵심’ 읽는 법
스웨거 화면에서 모든 걸 이해하려고 하면 피로가 빠르게 누적됩니다. 대신 아래 3개만 순서대로 보면 됩니다. 이 3개가 화면 설계에 직결됩니다.
① Method & Path: “이 API는 무엇을 하는가?”
먼저 왼쪽의 색깔 박스와 영어를 봅니다. 메서드(Method)는 “무슨 행동인지”, 경로(Path)는 “어떤 대상(리소스)을 다루는지”를 말해줍니다.
| 메서드 | 의미(기획자 번역) | 실무 예시 |
|---|---|---|
| GET | 정보 가져오기 | 상품 목록 조회, 내 프로필 보기 |
| POST | 새로 만들기/저장하기 | 회원가입, 장바구니 담기, 결제 요청 |
| PUT / PATCH | 수정하기 | 비밀번호 변경, 수량 변경, 프로필 수정 |
| DELETE | 삭제하기 | 장바구니 항목 삭제, 계정 삭제 |
실무 활용
기획서에 “수정” 기능이 있는데 Swagger 목록에 PUT이나 PATCH가 없다면?
지금이 딱 “수정 API가 필요한지”를 논의할 타이밍입니다. (QA 막바지에 발견하면 심장이 빠르게 뛸 수 있습니다)
② Parameters: “기획서에 정의한 값이 다 있나?”
Parameters는 API를 호출할 때 서버에 넘겨줘야 하는 조건 값입니다. 기획서의 필터, 검색, 정렬, 페이징, 상세 진입 같은 것들이 여기로 모입니다.
Name 값의 이름 (예: user_id, page, sort)
Required 필수 여부 (필수면 기획서에서도 “필수 입력/필수 조건”으로 정렬)
Description 제약/설명 (예: 최대 10자, 허용 값: newest|popular)
기획 체크리스트
1) 화면에 “필터”가 있다 → 파라미터에 그 필터 값이 실제로 존재하는가?
2) “페이지네이션”이 있다 → page, size 같은 값이 있는가?
3) 입력 제한이 있다 → Description에 제한이 적혀 있다면 기획서의 입력 제한도 맞춰야 한다
③ Responses (200 OK): “화면에 그릴 재료가 있는가?”
Responses는 API 호출이 성공했을 때 서버가 돌려주는 결과 데이터입니다. 기획자에게는 사실상 “화면에 올릴 수 있는 재료 목록”이 여기서 확정됩니다.
여기서 꼭 볼 것
Example Value 실제 응답 예시(샘플 데이터)
Schema 응답 구조(필드명, 타입, 중첩 구조)
체크 포인트
와이어프레임에 “판매자 이름”을 넣었는데 응답에 seller_name이 없다면?
그 정보는 현재 API 기준으로는 화면에 노출할 수 없습니다.
이때 선택지는 두 가지입니다: (1) 화면에서 빼기 (2) 서버에 필드/엔드포인트 추가 요청하기
3) “Try it out” 버튼 활용하기 (기획자의 무기)
스웨거의 가장 큰 장점은 문서를 “읽는 것”을 넘어, 직접 호출해서 확인할 수 있다는 점입니다. 기획자는 여기서 갑자기 초능력을 얻습니다. 이름하여 “대화 감소 빔” 🔦
- 확인할 API 엔드포인트를 펼칩니다(Expand).
- 오른쪽 상단의 Try it out을 누릅니다.
- Parameters(조건 값)나 Request Body(요청 본문)에 값을 입력합니다.
- Execute를 눌러 호출합니다.
- 하단의 Server Response에서 실제 응답 데이터(필드/값)를 확인합니다.
실무 팁: “이 화면에 필요한 데이터가 다 있나?”를 판단할 때, Try it out으로 받은 응답을 보면서 와이어프레임의 라벨을 하나씩 체크하면 누락이 빠르게 잡힙니다.
4) 보너스: 기획자가 자주 놓치는 4가지(여기서 일정이 갈립니다)
① 인증(Authorize): 401/403이 뜨면 대부분 여기
Try it out을 눌렀는데 401 또는 403이 뜬다면, “API가 고장”이라기보다 “출입증(토큰/키)이 없음”인 경우가 많습니다.
체크: Swagger UI 상단에 Authorize 버튼이 있는지 확인하고, 필요한 토큰/키를 넣은 뒤 다시 Execute 해보세요.
② 상태 코드(Status Code): 200만 보지 말고, 실패도 스펙입니다
기획서에 “에러 케이스”를 적을 때, Swagger의 응답 코드가 힌트가 됩니다. 예: 400(입력값 문제), 404(대상 없음), 500(서버 오류) 같은 것들이요.
기획 문장 샘플
“조회 API가 404를 반환하면 ‘삭제되었거나 접근할 수 없는 항목입니다’ 안내를 노출하고 리스트로 이동 버튼을 제공한다.”
③ 페이징/정렬: 목록 화면이 ‘끝없이 스크롤’인지 ‘페이지’인지 결정
목록 API에 page/size가 있으면 전통적 페이지네이션일 가능성이 높고, cursor/last_id가 있으면 무한 스크롤(커서 기반)일 가능성이 큽니다. 이 차이는 UI와 QA 범위를 크게 바꿉니다.
④ 필드명 네이밍: 화면 문구와 ‘데이터 키’는 다릅니다
화면 라벨이 “작성자”여도, 응답 키는 author, writer_name, createdBy일 수 있습니다. 기획서에 “표시 텍스트”와 “매핑 키”를 같이 적어두면 개발-디자인-기획 사이의 번역 비용이 확 줄어듭니다.
5) 결론: API를 아는 기획자는 일정이 정확합니다
API 명세서를 읽는 능력은 개발 지식을 과시하기 위한 기술이 아닙니다. 불필요한 커뮤니케이션을 줄이고, 데이터 유무를 미리 파악해 기획 재작업을 막고, 결과적으로 일정을 정확하게 맞추기 위한 실무 스킬입니다.
오늘의 결론 한 줄:
Method & Path로 “가능한 기능”을 확인하고, Parameters로 “필요한 입력”을 맞추고, Responses로 “그릴 수 있는 화면”을 확정한다.
FAQ
QSwagger(스웨거)는 OpenAPI랑 같은 건가요?
A 실무에서는 함께 묶여서 쓰입니다. OpenAPI는 “API를 어떻게 설명할지”에 대한 표준 형식이고, Swagger UI는 그 문서를 사람이 보기 좋은 화면으로 보여주는 도구로 많이 사용됩니다.
QResponses에 없는 필드는 화면에 못 그리나요?
A 원칙적으로는 어렵습니다. 응답 예시나 스키마에 필요한 필드가 없다면 “현재 API로는 재료가 없다”는 뜻입니다. 이때는 (1) 화면에서 해당 요소를 제거하거나, (2) 서버에 필드/엔드포인트 추가를 요청하는 쪽으로 판단이 갈립니다.
QTry it out을 눌렀는데 401/403이 떠요. 뭐가 문제죠?
A 대부분 인증 정보가 없어서 생깁니다. Swagger UI 상단의 Authorize 버튼(또는 보안 설정 섹션)이 있는지 확인하고, 필요한 토큰/키를 넣은 뒤 다시 Execute 해보세요.
QGET/POST/PUT/PATCH/DELETE를 기획서에 어떻게 활용하면 좋나요?
A 기획서의 기능 목록을 CRUD(조회/생성/수정/삭제)로 나누고, Swagger의 메서드 분포를 대조해보면 빠르게 공백이 보입니다. “수정 기능이 있는데 PATCH가 없다” 같은 이슈가 초기에 잡히면, 일정이 안정됩니다.