# 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 예시:
   ```json
   { "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. 백엔드 실행

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

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

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

```powershell
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](../DependencyInjection.cs) — Swagger doc group 설정
- [Backend Web.Api/Program.cs](../Program.cs) — Swagger middleware