postman-collection

v1.0.0

API를 만들거나 고친 뒤 라우터·검증 스키마·enum·인증 미들웨어를 소스에서 읽어 파라미터마다 허용값이 적힌 Postman 컬렉션 JSON을 만들거나 갱신

설치

호출 이름/postman-collection:postman-collection-from-code

postman-collection-from-code

API를 만들거나 고친 직후, 소스에서 읽어 Postman 컬렉션 JSON을 만듭니다. 그대로 import하면 되고, 받는 사람이 파라미터 값을 되묻지 않습니다.

뭘 하는지

라우터 → 검증 스키마 → enum → 인증 미들웨어 → 리포지토리 순서로 5군데를 읽고, 거기서 나온 사실만으로 컬렉션을 채웁니다. 확인 못 한 건 채우지 않고 ※ 확인 필요로 남깁니다.

결과물의 특징은 설명이 파라미터 옆에 붙는다는 것입니다.

{
  "key": "progressCode",
  "value": "PENDING",
  "description": "진행 상태. 미전달 시 전체 조회.\nPENDING 대기 | RUNNING 진행 | HOLD 보류 | REVIEW 검토\n※ 종료일시 정렬은 종료 상태와 같이 써야 의미가 있다"
}

Postman의 Params 탭에는 Description 열이 있습니다. 여기에 값이 있으면 요청을 수정하는 화면에서 바로 보이고, 컬렉션 설명에 몰아쓰면 아무도 안 봅니다.

왜 이렇게 설계했나

인증 방식을 옆 컬렉션에서 복붙하지 않는다

같은 레포의 다른 API가 Authorization: Bearer를 쓴다고 이 라우트도 그렇다는 보장이 없습니다. 실제로 이름이 JWT처럼 보이는 미들웨어가 헤더가 아니라 signed cookie를 읽고 있어서, 관례대로 Bearer를 넣었으면 컬렉션 전체가 401만 뱉을 상황이 있었습니다.

그래서 절차에 미들웨어 본문을 열어 어디서 토큰을 읽는지 확인하는 단계를 못 박았습니다. 5군데 중 가장 자주 생략되는 곳입니다.

"허용된 값만 사용 가능합니다"는 설명이 아니다

검증 스키마의 에러 메시지를 그대로 옮기면 이런 문장이 나옵니다. 받는 사람은 그 값이 뭔지 몰라서 결국 물어봅니다. enum 파일까지 따라가서 코드와 한글 라벨을 전부 나열하게 했습니다. 지역 코드 13개, 상태 코드 7개를 적는 데 드는 비용보다 왕복 한 번이 비쌉니다.

파라미터가 아닌데 결과를 바꾸는 것들

코드에 하드코딩된 제외 조건 — 특정 상태값 제외, 특정 조합 제외 — 은 Params 탭에 자리가 없습니다. 그래서 빠뜨리기 쉽고, 빠지면 "필터 걸었는데 0건"의 원인을 아무도 못 찾습니다. request description에 ■ 조회 제외 규칙 (파라미터 아님, 항상 적용) 섹션으로 반드시 남깁니다.

설명을 3층으로 나눈다

같은 내용을 두 곳에 쓰면 한쪽이 낡습니다. 무엇에 대한 설명인가로 위치를 정합니다.

위치	담는 것
collection description	API군 전체, 유사 API와의 차이, 인증, 공유 코드표
query[].description	그 파라미터 하나
request description	서버측 제외 규칙, 고정 동작, 응답 구조, 에러 코드

갱신이 기본, 생성이 예외

API 수정 요청은 대부분 이미 있는 컬렉션의 갱신입니다. 새 파일을 만들면 두 벌이 돌아다니면서 어느 게 최신인지 알 수 없게 됩니다. 먼저 기존 컬렉션을 찾고, 해당 item만 고치고, 바뀐 파라미터만 손대고, 삭제된 파라미터는 지웁니다.

쓰는 법

API를 만들거나 고친 뒤에 이렇게 말하면 됩니다.

포스트맨 컬렉션 만들어줘
방금 고친 API 컬렉션에 반영해줘
프론트한테 넘길 수 있게 json으로 뽑아줘

저장 위치는 레포에 기존 컬렉션이 있으면 그 관례를 따르고, 없으면 물어봅니다.

안 쓰는 경우

소스에 OpenAPI/Swagger 스펙이 이미 있는 프로젝트 — Postman이 그걸 직접 import합니다
소스가 없는 외부 서드파티 API — 읽을 곳이 없으면 결국 추측이 됩니다

에이전트가 읽는 절차 — SKILL.md

설치하면 Claude가 실행 중에 참조하는 실제 문서다. 아래 내용이 그대로 동작을 결정한다.

Postman Collection from Code

Overview

방금 만들거나 고친 API를 소스에서 읽어 Postman v2.1 컬렉션 JSON으로 뽑는다. 목적은 "요청이 나가는 것"이 아니라 받는 사람이 되묻지 않는 것이다.

핵심 원칙 세 가지:

추측 금지. 파라미터 이름·필수 여부·기본값·허용 코드값·인증 방식은 전부 소스에서 확인한다. 확인 못 한 건 그럴듯하게 채우지 않고 ※ 확인 필요로 남긴다.
설명은 설명 대상 옆에. 파라미터 설명은 그 파라미터의 description에 붙인다. 컬렉션 description에 몰아쓰면 Params 탭에서 안 보이므로 아무도 안 읽는다.
허용값은 전부 나열한다. "허용된 값만 사용 가능"은 설명이 아니다. CODE001 라벨A | CODE002 라벨B | ... 형태로 코드와 한글 라벨을 함께 적는다. 이 한 줄이 프론트와의 왕복을 없앤다.

When to Use

새 엔드포인트를 만든 직후, 또는 기존 엔드포인트의 파라미터·정렬·응답이 바뀐 직후
"포스트맨 만들어줘 / 컬렉션 뽑아줘 / import 할 수 있게 / 프론트한테 넘길 것" 류의 요청
API 스펙을 사람에게 넘겨야 하는데 Swagger가 없는 프로젝트

Not for: 이미 OpenAPI/Swagger 스펙이 소스에 있는 프로젝트(그걸 Postman이 직접 import한다), 외부 서드파티 API(소스가 없어 추측이 된다).

절차

1. 읽을 곳 5군데를 순서대로 확인한다

각 단계에서 얻은 사실은 path/file.ts:42 형태로 근거를 남긴다. 하나라도 건너뛰면 그 자리가 추측으로 채워진다.

순서	읽을 것	얻는 것
1	라우터 등록 줄	HTTP method, 경로, 미들웨어 체인
2	검증 스키마 (Joi / zod / class-validator)	파라미터 이름, 필수 여부, 기본값, min·max, 허용값 목록, 배열 허용 여부
3	enum / 상수 파일	허용 코드값의 실제 값과 한글 라벨
4	인증 미들웨어 본문	Bearer 인지 쿠키인지 API Key인지
5	서비스 / 리포지토리	파라미터가 아닌데 결과에 영향 주는 서버측 규칙, 응답 필드

4번은 관례로 때려맞추지 않는다. 같은 레포의 다른 컬렉션이 Authorization: Bearer를 쓴다고 해서 이 라우트도 그렇다는 보장이 없다. 미들웨어가 실제로 어디서 토큰을 읽는지(req.headers.authorization / req.signedCookies / 커스텀 헤더) 본문을 열어 확인한다. 인증 방식이 틀리면 컬렉션 전체가 401만 뱉는다.

5번을 빼먹으면 "왜 0건 나오죠" 문의가 온다. 코드에 하드코딩된 제외 조건(상태값 제외, 특정 조합 제외), 고정 정렬, 서버가 강제하는 상한 같은 것들이다. 파라미터가 아니라서 Params 탭에는 자리가 없지만, 결과를 좌우하므로 request description에 반드시 적는다.

2. 설명을 3층으로 나눈다

같은 내용을 두 곳에 쓰지 않는다. 어디에 쓸지는 **"무엇에 대한 설명인가"**로 정한다.

collection description — 이 API군 전체

이 API가 뭘 하는 건지 두세 줄
비슷한 기존 API가 있으면 그것과의 차이를 번호로 (이게 제일 많이 읽힌다)
인증 방식과 필요한 헤더/쿠키
여러 요청이 공유하는 코드 표 (마크다운 테이블)
"필터를 다 켠 상태로 만들어 뒀으니 필요 없는 건 Params 탭에서 체크 해제하라"는 안내

query[].description — 그 파라미터 하나

타입·범위·기본값 (0 이상, 기본값 0)
필수면 앞에 [필수]
허용 코드값 전체 나열 (PENDING 대기 | RUNNING 진행 | ...)
복수 전달이면 그 형태 (key=A&key=B 형태로 반복)
미전달 시 동작 (미전달 시 전체 조회)
그 파라미터에만 걸리는 함정은 ※로 (※ 종료일시 정렬은 종료 상태와 같이 써야 의미가 있다)

request description — 파라미터가 아닌 것

항상 적용되는 서버측 제외 규칙
고정 정렬 / 고정 건수
응답 구조와 필드 목록
에러 코드와 발생 조건
성능 특성 (측정한 적 있으면 숫자로)

3. 파라미터는 전부 켠 채로 넣는다

받는 사람이 지우는 건 쉽고, 없는 걸 찾아 넣는 건 어렵다.

선택 파라미터도 예시값을 채워 활성 상태로 둔다. 안내는 collection description 마지막 줄에.
상호 배타적인 파라미터만 "disabled": true로 두고, 왜 껐는지 description에 적는다.
복수 전달 파라미터는 같은 key로 두 줄 넣는다. 두 번째 줄 description은 (위 <key>의 두 번째 값 — 복수 전달 예시).
raw URL과 query[] 배열의 내용을 일치시킨다. Postman은 raw를 우선 표시하므로 어긋나면 사용자가 혼란스럽다.

4. 변하는 값은 컬렉션 variable로

base URL은 프로젝트에서 이미 쓰는 변수명을 따른다 — 기존 컬렉션이 있으면 열어서 확인하고, 없으면 {{server}}. 실제 호스트를 하드코딩하지 않는다.

토큰·ID처럼 사람마다 다른 값도 변수로 빼고, 기본값은 CHANGE_ME / SET_..._HERE처럼 채워야 한다는 게 드러나는 문자열로 둔다.

5. 기존 컬렉션이 있으면 갱신한다

API 수정 요청은 대부분 신규 생성이 아니라 갱신이다. 먼저 찾는다:

find . -iname "*postman*" -not -path "./node_modules/*"

해당 엔드포인트 item이 이미 있으면 그 item만 고친다. 새 파일을 만들면 두 벌이 돌아다니게 된다.
바뀐 파라미터만 손대고 나머지 description은 보존한다. 통째로 다시 쓰면 이전에 누가 손으로 채워둔 설명이 날아간다.
파라미터가 삭제됐으면 지운다. 남겨두면 422를 유발한다.
같은 레포의 기존 컬렉션 파일 위치와 명명 규칙을 그대로 따른다.

6. 저장하고 검증한다

레포에 관례가 있으면 따르고, 없으면 어디 둘지 묻는다.

작성 직후 파싱을 확인한다. heredoc으로 긴 JSON을 쓰면 이스케이프가 깨지기 쉽다:

node -e "JSON.parse(require('fs').readFileSync('<파일경로>','utf8'));console.log('JSON OK')"

\n은 JSON 문자열 안의 이스케이프로 들어가야 실제 줄바꿈으로 렌더링된다. 마크다운 테이블도 \n으로 이어 붙이면 Postman이 렌더링한다.

7. 넘길 때 한 줄 덧붙인다

컬렉션에 담지 못한 것 — 응답에 없는 필드, 확인 못 한 동작, 다른 컬렉션과 다른 인증 방식 — 을 사용자에게 말로 알린다. JSON 안의 ※ 확인 필요는 나중에 읽히지만, 지금 결정이 필요한 건 지금 말해야 한다.

Common Mistakes

인증 방식을 옆 컬렉션에서 복붙한다. 미들웨어 본문을 안 열어보고 Bearer를 넣으면 전부 401이 난다. 5군데 중 4번이 제일 자주 생략된다.
"허용된 값만 사용 가능합니다"로 끝낸다. 검증 스키마의 에러 메시지를 그대로 옮긴 것인데, 받는 사람은 그 값이 뭔지 몰라서 결국 물어본다. enum 파일까지 따라가서 값과 라벨을 나열한다.
description을 한 덩어리로 몰아쓴다. 컬렉션 설명에 파라미터 15개를 다 적으면 Params 탭은 비어 있다. 사람은 자기가 보고 있는 화면에 있는 것만 읽는다.
서버측 제외 규칙을 뺀다. 파라미터가 아니라서 넣을 자리가 없다고 생각하지만, 이게 빠지면 "필터 걸었는데 0건"의 원인을 아무도 못 찾는다.
기존 컬렉션을 놔두고 새 파일을 만든다. 어느 게 최신인지 알 수 없게 된다.
raw URL과 query[]가 어긋난다. 파라미터를 추가하면서 한쪽만 고친 경우다.
응답 필드를 코드 확인 없이 적는다. 리포지토리의 attributes / select 목록을 실제로 보고 적는다. 모델에 있다고 응답에 있는 게 아니다.

GitHub에서 소스 보기 →