API 문서 작성 가이드라인

Swagger(OpenAPI) 문서와 릴리즈 노트 작성 기준을 정의합니다.

---

Swagger 문서

기본 원칙

• 상세 정보는 Swagger에: 에러 코드, 요청/응답 필드 설명, 형식 예시 등 모든 기술적 상세는 Swagger에 작성
• 릴리즈 노트는 변경 사실만: Swagger를 보면 알 수 있는 내용은 릴리즈 노트에 반복하지 않음

---

@ApiOperation

summary는 한 줄 요약, description은 마크다운으로 상세 설명을 작성합니다.

@ApiOperation({
  summary: '앱 설정 정보 조회',
  description:
    '모바일 앱 초기화 시 필요한 통합 시스템 설정 정보를 조회합니다.\n\n' +
    '--- \n\n' +
    '**응답 주요 필드**:\n' +
    '- `id`: 현재 AppSettings 버전의 고유 식별자\n' +
    '- `appVersion`: 앱 버전 호환성 정보 (updateRequired, forceBlocked, minimumVersion)\n\n' +
    '**인증**: `Accept-Language` 헤더로 응답 언어를 지정합니다. (기본값: `de-DE`)',
})

규칙

• description은 기능 요약 → --- 구분선 → 주요 필드/동작 설명 순서로 작성
• 필드 설명은 ` 으로 감싸서 명시
• 비즈니스 로직이 복잡한 엔드포인트는 버전 비교 로직, 클라이언트 처리 방법 등을 포함

---

@ApiHeader

@ApiHeader({
  name: 'User-Agent',
  description: 'User-Agent: {product}/{version} ({platform}; {os}; {device}; {channel}; locale/{locale})',
  required: true,
  example: 'dha-sleep-app/2.3.1 (iOS; iOS 17.5; iPhone14,5; AppStore; locale/ko-KR)',
})
@ApiHeader({
  name: 'Accept-Language',
  description: '언어 태그',
  required: false,
  example: 'de-DE',
  enum: ['ko-KR', 'en-US', 'de-DE'],
})

---

@ApiResponse

성공 응답

@ApiResponse({
  status: 200,
  description: '앱 설정 정보 조회 성공',
  type: MobileAppSettingsResponseDto,
})

에러 응답 — 단일 예시

@ApiResponse({
  status: 401,
  description: '인증 실패',
  content: {
    'application/json': {
      example: {
        status: 401,
        code: 2001,
        message: 'UNAUTHORIZED',
        detail: '유효하지 않은 앱 토큰입니다.',
      },
    },
  },
})

에러 응답 — 복수 예시 (examples)

케이스가 2개 이상일 때 examples를 사용합니다.

@ApiResponse({
  status: 400,
  description: '유효하지 않은 User-Agent 헤더',
  content: {
    'application/json': {
      examples: {
        missingUserAgent: {
          summary: 'User-Agent 헤더 누락',
          value: {
            status: 400,
            code: 8005,
            message: 'INVALID_USER_AGENT',
            detail: 'User-Agent 헤더가 누락되었거나 올바른 형식이 아닙니다',
          },
        },
        invalidUserAgent: {
          summary: 'User-Agent 파싱 실패',
          value: {
            status: 400,
            code: 8005,
            message: 'INVALID_USER_AGENT',
            detail: 'User-Agent 헤더가 누락되었거나 올바른 형식이 아닙니다',
          },
        },
      },
    },
  },
})

에러 응답 작성 기준

HTTP 상태	포함할 케이스
400	입력값 검증 실패 (헤더 누락/형식 오류, 쿼리 파라미터 오류 등)
401	인증 토큰 없음/만료
403	권한 부족
404	리소스 없음
500	도메인 에러, 서버 내부 오류

에러 응답 필드 구조

{
  "status": 400,
  "code": 8005,
  "message": "INVALID_USER_AGENT",
  "detail": "사람이 읽을 수 있는 상세 설명"
}

• code: MobileErrorCode enum 값 (도메인별 범위 구분)
• message: enum key 문자열 (errorNameKey)
• 검증 오류는 errors 배열 추가 가능

---

에러 코드 추가 절차

도메인 전용 에러 코드가 필요할 때 아래 3개 파일을 순서대로 수정합니다.

1. mobile-error-codes.enum.ts

export enum MobileErrorCode {
  INVALID_USER_AGENT = 8005,  // 추가
}

2. mobile-error-messages.ref.ts

[MobileErrorCode.INVALID_USER_AGENT]: {
  message: 'INVALID_USER_AGENT',
  detail: 'User-Agent 헤더가 누락되었거나 올바른 형식이 아닙니다',
},

3. mobile.errors.ts

export class InvalidUserAgentError extends DomainError {
  constructor(metadata?: ErrorMetadata) {
    super(
      MobileErrorCode.INVALID_USER_AGENT,
      MOBILE_ERROR_MESSAGES[MobileErrorCode.INVALID_USER_AGENT].detail,
      HttpStatus.BAD_REQUEST,
      MOBILE_ERROR_MESSAGES[MobileErrorCode.INVALID_USER_AGENT].message,
      metadata
    );
  }
}

---

릴리즈 노트

위치

apps/dta-wi-doc/docs/release-notes/backend/dta-wide-api/history/v{버전}.md

원칙

• 클라이언트 개발자가 무엇이 바뀌었는지 한눈에 파악할 수 있도록 작성
• 기술적 상세(에러 코드, 필드 설명, 요청 형식 등)는 Swagger 참고를 유도하고 노트에는 반복하지 않음
• 엔드포인트 단위로 변경사항을 기술

섹션 구조

# v{버전} 릴리즈 노트

**릴리즈 날짜:** {날짜}
**타입:** Major | Minor | Patch Release
**호환성:** {이전 버전}과 하위호환성 유지 | 파괴적 변경 포함

---

## 🎯 주요 기능
신규 엔드포인트 및 기능을 기능 단위로 묶어서 설명.
각 기능마다 Endpoint 테이블 포함.

---

## 🔄 변경된 엔드포인트
기존 엔드포인트의 요청/응답 변경사항.
Deprecated 필드, 신규 필드 위주로 기술.

---

## ❌ 제거된 엔드포인트
제거된 엔드포인트와 대체 방법을 명시.

---

## 🔧 기술적 개선
클라이언트에 영향 없는 내부 개선사항.

---

## 🔗 참고 자료

작성 예시

신규 엔드포인트

### 3. 📱 App Version Policy

#### Endpoint

| Method | Path | 설명 | 인증 |
|--------|------|------|------|
| `POST` | `/v1/mobile/admin/app-version-policy` | 앱 버전 정책 생성 (관리자 전용) | User JWT |

변경된 엔드포인트

### `GET /v1/mobile/app-settings`
- `appVersion` 필드 추가 (`updateRequired`, `forceBlocked`, `minimumVersion`, `latestVersion`, `deprecatedAt`)
- `mobile` 필드 Deprecated → `appVersion`으로 대체

제거된 엔드포인트

| Method | Path | 대체 |
|--------|------|------|
| `GET` | `/v1/mobile/app-version/check` | `GET /v1/mobile/app-settings` 응답의 `appVersion` 필드로 통합 |

작성 시 체크리스트

• 신규 엔드포인트는 Method, Path, 설명, 인증 방식 포함
• 변경된 엔드포인트는 추가/삭제/Deprecated 필드만 명시 (상세는 Swagger)
• 제거된 엔드포인트는 반드시 대체 방법 명시
• 클라이언트에 영향 없는 내부 변경은 🔧 기술적 개선 섹션에
• Swagger에서 확인 가능한 내용(에러 코드, 요청 형식 등)은 반복하지 않음