ANTOOZA-BACKEND/Web.Api/postman

ANTOOZA Postman Collection

Backend 의 모든 API 를 Postman 에서 테스트할 수 있는 import 파일 모음입니다.

폴더 구조

postman/
├── README.md                                       ← 이 파일
├── update.ps1                                      ← 갱신 스크립트
│
├── collections/
│   └── ANTOOZA-Internal-API.postman_collection.json   ← /api/* (내부/관리자)
│
├── ANTOOZA-Local.postman_environment.json             ← https://localhost:4000
├── ANTOOZA-Dev.postman_environment.json               ← https://dev-api.antooza.com
├── ANTOOZA-Prod.postman_environment.json              ← https://api.antooza.com
│
└── _legacy/                                        ← 이전 수동 작성 11개 collection (보관용)
    ├── Account.postman_collection.json
    ├── Auth.postman_collection.json
    └── ...

개발자 포털 공개 API(/v1/*, /oauth/token) 는 2026-07-03 제거되었습니다. ANTOOZA-Public-API collection 도 함께 삭제됐습니다.

Internal Collection 의 주요 그룹:

• MyPage (27) — 내 정보, 포인트, 충전
• Forum (23) — 게시판 (post / comment / reaction / report)
• Feed (16) — 피드 / 댓글 / 좋아요 / 북마크
• Store (14) — 상점 (orders / inventory / channels)
• Auth (11) — 로그인 / 회원가입 / 비밀번호 / 이메일 인증
• Widget (10) — OBS 위젯 endpoint
• ChannelTitle (7), Note (6), Channel (5), Studio (4), Payment (5), ...

---

1. Postman 에서 Import

1-1. Collection import

1. Postman → 좌측 Collections 패널 상단 Import 클릭
2. collections/ANTOOZA-Internal-API.postman_collection.json 드래그

1-2. Environment import

1. Postman → 좌측 Environments 패널 상단 Import 클릭
2. 사용할 환경 파일을 import (필요한 개수만큼):
   • ANTOOZA-Local.postman_environment.json (로컬 개발)
   • ANTOOZA-Dev.postman_environment.json (DEV 서버)
   • ANTOOZA-Prod.postman_environment.json (PROD 서버)
3. 우측 상단 environment selector 에서 사용할 환경 선택

Collection 안의 모든 request 가 {{baseUrl}}/... 형식이라 environment 만 바꾸면 호출 대상이 전환됩니다.

---

2. 환경 변수

변수	용도	설정 방법
baseUrl	API host	environment 별로 사전 설정됨 (변경 X)
accessToken	JWT Bearer (Authorization: Bearer ...)	로그인 후 응답에서 복사
refreshToken	refresh token	로그인 응답에서 복사
channelSID	채널 SID (스튜디오/위젯 호출용)	본인 채널 정보에서 복사
memberSID	회원 SID (특정 회원 조회)	필요 시 수동 입력
memberID	회원 ID (숫자)	필요 시 수동 입력

2-1. 첫 로그인 → 토큰 채우기

1. Internal Collection → Auth 폴더 → POST /api/auth/login 실행

2. body 예시:

   { "email": "you@dpot.dev", "password": "your-password" }
   

3. 응답의 data.accessToken / data.refreshToken 복사

4. Environment editor 에서 accessToken / refreshToken 의 Current Value 에 붙여넣기

5. 이후 모든 인증 필요 request 는 자동으로 Bearer 헤더 사용

---

3. Collection 갱신

백엔드에 endpoint 가 추가/변경되면 collection 도 다시 생성해야 합니다.

3-1. 백엔드 실행

cd E:\workspace\antooza\Backend
dotnet run --project Web.Api

https://localhost:4000/health 이 200 으로 응답하는지 확인.

3-2. 갱신 스크립트 실행

cd E:\workspace\antooza\Backend\Web.Api\postman
pwsh ./update.ps1

옵션:

• -ApiBase https://localhost:4000 (기본값)

스크립트 동작:

1. $ApiBase/health 응답 확인
2. $ApiBase/swagger/internal/swagger.json fetch
3. npx openapi-to-postmanv2@5 로 Postman Collection v2.1 변환
4. collections/ANTOOZA-Internal-API.postman_collection.json 덮어쓰기

3-3. Postman 에 재import

갱신된 파일을 Postman 에서 Import → Replace existing collection 으로 적용.

Environment 파일은 변하지 않으니 한 번만 import 하면 됩니다.

---

4. 주의사항

Internal swagger 는 Production 에 차단됨

https://api.antooza.com/swagger/internal/swagger.json     → 404 (보안 차단)
https://api.antooza.com/swagger/internal/swagger.json → 404 (보안 차단)
https://localhost:4000/swagger/internal/swagger.json    → 200 ← 변환은 여기서만

update.ps1 은 기본적으로 localhost:4000 을 호출합니다. 그래서 백엔드를 반드시 로컬에서 띄워야 internal collection 을 갱신할 수 있습니다.

자체 서명 인증서

localhost:4000 은 dev 자체 서명 인증서를 사용합니다. update.ps1 은 -SkipCertificateCheck 옵션으로 우회하지만, Postman 자체는 별도 설정이 필요할 수 있습니다:

Postman → Settings → General → SSL certificate verification OFF (로컬 호출 시에만)

PROD/DEV 호출 시에는 정상 와일드카드 인증서 (*.antooza.com) 라 ON 으로 유지해도 됩니다.

_legacy/ 폴더

기존에 수동 작성된 11개 collection 입니다 (Account, Auth, Channel, Donation, Etc, Forum, Note, Notification, Payment, Studio, Wallet). 한국어 endpoint 이름과 example body 가 직접 정리되어 있어 참고용으로 보관합니다.

새로운 자동 생성 collection 이 swagger 기반이라 endpoint 이름은 영어 (operationId / summary) 입니다. 한국어 이름이 필요하면 endpoint 의 [EndpointSummary("...")] 또는 XML doc 주석을 수정 후 백엔드 빌드 → update.ps1 재실행 하세요.

---

5. 트러블슈팅

증상	원인 / 해결
update.ps1 가 backend 접근 실패	dotnet run --project Web.Api 가 실행 중인지 확인. 포트 4000 점유 여부 확인
internal swagger 404	PROD/DEV 에서 swagger fetch 시도. localhost 로 변경
Postman import 시 한국어 깨짐	파일 인코딩은 UTF-8 (BOM 없음). Postman 9+ 권장
Authorization 헤더가 안 들어감	environment 가 선택돼 있고 accessToken 변수에 값이 채워졌는지 확인
401 Unauthorized	accessToken 만료 (1시간). 다시 로그인
CORS 오류	Postman 자체는 CORS 영향 없음. 브라우저에서 직접 호출 시 발생 가능

---

6. 관련 문서

• Backend Web.Api/DependencyInjection.cs — Swagger doc group 설정
• Backend Web.Api/Program.cs — Swagger middleware