ANTOOZA-BACKEND/Web.Api/postman

DPOT Postman Collection

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

폴더 구조

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

현재 endpoint 수 (2026-06-08 기준)

Collection	Tag/Folder	Requests
DPOT-Public-API	5 (OAuth, 회원, 상품, 쿠폰, 통계)	6
DPOT-Internal-API	34 (Auth, MyPage, Forum, Feed, Store, Studio, Donation, Developers, Widget, ...)	231

Internal Collection 의 주요 그룹:

• MyPage (27) — 내 정보, 포인트, 충전, 출금
• Forum (23) — 게시판 (post / comment / reaction / report)
• Feed (16) — 피드 / 댓글 / 좋아요 / 북마크
• Developers (14) — 개발자 포털 (앱/토큰/통계/프로필/KYC)
• Store (14) — 상점 (orders / inventory / channels)
• StudioCrew (14) — 크루 관리 (스튜디오)
• Auth (11) — 로그인 / 회원가입 / 비밀번호 / 이메일 인증
• DonationRemote (11) — 후원 위젯 리모컨
• Widget (10) — OBS 위젯 endpoint
• Crew (8) — 크루 (사용자측)
• ChannelTitle (7), Note (6), Channel (5), Studio (5), Payment (5), ...

---

1. Postman 에서 Import

1-1. Collection import

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

1-2. Environment import

1. Postman → 좌측 Environments 패널 상단 Import 클릭
2. 사용할 환경 파일을 import (필요한 개수만큼):
   • DPOT-Local.postman_environment.json (로컬 개발)
   • DPOT-Dev.postman_environment.json (DEV 서버)
   • DPOT-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	로그인 응답에서 복사
clientId	OAuth2 Client ID (dpot_client_xxx)	developers.dpot.live/apps 에서 발급
clientSecret	OAuth2 Client Secret (dpot_secret_xxx)	앱 생성 시 1회 표시
pat	Personal Access Token (dpot_pat_xxx)	developers.dpot.live/tokens 에서 발급
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 헤더 사용

2-2. OAuth2 Client Credentials (Public API)

1. Public Collection → OAuth → POST /oauth/token

2. form-data:

   grant_type=client_credentials
   client_id={{clientId}}
   client_secret={{clientSecret}}
   scope=read:members read:products
   

3. 응답의 access_token 을 accessToken 변수에 저장

4. /v1/* 호출 시 자동 사용

2-3. PAT 사용

PAT 는 OAuth2 access token 발급 절차 없이 바로 사용:

Authorization: Bearer dpot_pat_xxxxxxxxxxxxxxxxxxxxxx

pat 변수에 저장 후, 필요한 request 에서 Authorization header 의 {{accessToken}} 부분을 {{pat}} 로 바꿔서 사용.

---

3. Collection 갱신

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

3-1. 백엔드 실행

cd D:\dpot\Backend
dotnet run --project Web.Api

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

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

cd D:\dpot\Backend\Web.Api\postman
pwsh ./update.ps1

옵션:

• -ApiBase https://localhost:4000 (기본값)
• -SkipPublic — public 변환 생략
• -SkipInternal — internal 변환 생략

스크립트 동작:

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

3-3. Postman 에 재import

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

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

---

4. 주의사항

Internal swagger 는 Production 에 차단됨

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

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

Public swagger 는 모든 환경에 노출되어 있어서, 정 필요하면 PROD 에서도 가져올 수 있습니다:

pwsh ./update.ps1 -ApiBase https://api.dpot.live -SkipInternal

자체 서명 인증서

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

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

PROD/DEV 호출 시에는 정상 와일드카드 인증서 (*.dpot.live) 라 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 로 변경하거나 -SkipInternal 사용
Postman import 시 한국어 깨짐	파일 인코딩은 UTF-8 (BOM 없음). Postman 9+ 권장
Authorization 헤더가 안 들어감	environment 가 선택돼 있고 accessToken 변수에 값이 채워졌는지 확인
401 Unauthorized	accessToken 만료 (1시간). 다시 로그인 또는 OAuth2 token 재발급
CORS 오류	Postman 자체는 CORS 영향 없음. 브라우저에서 직접 호출 시 발생 가능

---

6. 관련 문서

• 개발자 포털 plan
• 공개 API 문서 (Scalar) — 외부 개발자용
• Backend Web.Api/DependencyInjection.cs — Swagger doc group 설정
• Backend Web.Api/Program.cs — Swagger middleware