TIL - 20260714

juni·2026년 7월 14일

목록 보기

403/468

0714 백엔드 실무 심화 (21/N): API 문서화, Swagger와 내부 개발 문서 관리

✅ 1. API 문서화란 무엇인가?

API 문서화는 백엔드가 제공하는 API의 요청 방식, 응답 구조, 인증 방식, 에러 코드, 사용 예시를 정리하는 작업입니다.
프론트엔드, 관리자 페이지, 외부 연동, QA, 운영 대응에서 API 문서가 있으면 훨씬 빠르게 개발하고 문제를 찾을 수 있습니다.
1인 개발자라도 API 문서는 필요합니다. 지금은 혼자 알아도, 몇 주 뒤의 나는 기억이 안 날 수 있기 때문입니다.

API 문서에 들어갈 내용:
- URL
- HTTP Method
- 인증 필요 여부
- 권한
- Request Body
- Query Parameter
- Response Body
- Error Response
- 사용 예시
- 주의사항

➕ 1-1. API 문서가 필요한 이유

프론트엔드에서 어떤 값을 보내야 하는지 명확해집니다.
백엔드 응답 구조를 바꿀 때 영향 범위를 확인할 수 있습니다.
관리자 기능 QA 기준을 만들기 쉽습니다.
외부 API/Webhook 연동을 설명하기 쉽습니다.
장애 발생 시 어떤 API가 영향을 받았는지 빠르게 파악할 수 있습니다.
인수인계, 경력 정리, 연봉협상 자료로도 활용할 수 있습니다.

문서 없는 API:
코드를 직접 뒤져야 함

문서 있는 API:
URL, 요청값, 응답값, 권한, 에러를 바로 확인 가능

✅ 2. 좋은 API 문서의 기준

API 문서는 “있다”보다 “실제로 쓸 수 있다”가 중요합니다.
단순 URL 목록만 있으면 실무에서는 부족합니다.

➕ 2-1. 좋은 API 문서에 필요한 요소

항목	설명
API 목적	이 API가 어떤 기능인지
Method/URL	`GET /api/admin/consults`
인증 여부	로그인 필요 여부
권한	ADMIN 이상, MANAGER 본인 담당만
Query Parameter	검색, 필터, 페이지네이션
Request Body	생성/수정 시 필요한 값
Response Body	성공 응답 구조
Error Response	400, 401, 403, 404, 409, 500
예시	실제 요청/응답 예시
주의사항	개인정보, 상태 전이, 중복 요청 기준

➕ 2-2. 나쁜 문서 예시

POST /consult
상담 신청

어떤 body를 보내야 하는지 모릅니다.
성공 응답이 뭔지 모릅니다.
중복 신청 시 어떻게 되는지 모릅니다.
프론트엔드나 QA에서 바로 쓰기 어렵습니다.

➕ 2-3. 좋은 문서 예시

## 상담 신청 생성

### Method / URL
POST /api/consults

### 인증
불필요

### Request Body
```json
{
  "name": "홍길동",
  "phone": "01012345678",
  "productId": 15,
  "source": "NAVER_AD",
  "visitorId": "visitor_abc123"
}

Response

{
  "success": true,
  "data": {
    "id": 123,
    "status": "PENDING",
    "createdAt": "2026-07-14T10:00:00.000Z"
  }
}

Error

400: 입력값 오류
409: 이미 신청된 정보
500: 서버 오류

주의사항

같은 이벤트/상품/전화번호 조합은 중복 신청 불가
알림톡 발송 실패와 상담 신청 저장은 분리 처리


*   이 정도로 적으면 프론트, QA, 운영 확인에 바로 사용할 수 있습니다.

---

### ✅ 3. Swagger란 무엇인가?

*   **Swagger**는 API 문서를 자동으로 생성하고 테스트할 수 있게 해주는 도구입니다.
*   NestJS에서는 `@nestjs/swagger`를 사용해 Controller, DTO, Decorator 기반으로 문서를 만들 수 있습니다.
*   Swagger를 붙이면 API 목록, 요청값, 응답값, 인증 여부를 브라우저에서 확인할 수 있습니다.

```txt id="swagger-basic"
NestJS Controller/DTO
  ↓
Swagger Decorator
  ↓
Swagger UI
  ↓
API 문서 + 간단한 테스트

➕ 3-1. Swagger의 장점

API 문서가 코드와 가까이 있어 유지보수하기 쉽습니다.
프론트엔드 개발자가 직접 API 구조를 확인할 수 있습니다.
Postman 없이도 간단한 요청 테스트가 가능합니다.
DTO를 기반으로 요청 body 구조를 보여줄 수 있습니다.
인증이 필요한 API도 Bearer Token을 넣고 테스트할 수 있습니다.

➕ 3-2. Swagger의 한계

문서 설명을 제대로 달지 않으면 보기 어려운 자동 문서가 됩니다.
실제 운영 정책이나 상태 전이 규칙은 별도 문서가 필요할 수 있습니다.
Swagger UI를 운영 환경에 그대로 공개하면 보안 위험이 될 수 있습니다.

✅ 4. NestJS Swagger 기본 설정

➕ 4-1. 설치

npm install @nestjs/swagger swagger-ui-express

➕ 4-2. main.ts 설정 예시

import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('Togethermall API')
    .setDescription('온라인 휴대폰 판매몰 API 문서')
    .setVersion('1.0.0')
    .addBearerAuth()
    .build();

  const document = SwaggerModule.createDocument(app, config);

  SwaggerModule.setup('api-docs', app, document);

  await app.listen(process.env.PORT ?? 3000);
}

bootstrap();

➕ 4-3. 접근 URL

http://localhost:3000/api-docs

로컬 개발 환경에서는 Swagger가 매우 유용합니다.
운영 환경에서는 접근 제한을 반드시 고려해야 합니다.

✅ 5. Swagger 보안 설정

Swagger는 API 구조를 보여주기 때문에 운영에서 아무나 접근하게 두면 위험합니다.
특히 관리자 API, 내부 API, Webhook URL, 권한 구조가 노출될 수 있습니다.

➕ 5-1. 운영에서 주의할 점

운영 Swagger 공개 시 노출 가능:
관리자 API 목록
요청/응답 구조
Webhook URL
권한 구조
내부 에러 예시
테스트용 API

➕ 5-2. 권장 방식

로컬/개발:
Swagger 사용

스테이징:
인증 또는 IP 제한 후 사용

운영:
비활성화하거나 관리자/IP 제한

➕ 5-3. 환경별 Swagger 활성화 예시

if (process.env.NODE_ENV !== 'production') {
  const config = new DocumentBuilder()
    .setTitle('Togethermall API')
    .setVersion('1.0.0')
    .addBearerAuth()
    .build();

  const document = SwaggerModule.createDocument(app, config);

  SwaggerModule.setup('api-docs', app, document);
}

운영에서도 꼭 필요하다면 Basic Auth, VPN, IP 제한, 관리자 인증 등을 붙여야 합니다.
단순히 URL을 어렵게 만드는 것은 보안이 아닙니다.

✅ 6. Controller 문서화

Swagger에서는 Controller와 Method에 Decorator를 붙여 API 설명을 작성할 수 있습니다.

➕ 6-1. Controller 예시

@ApiTags('Admin Consults')
@ApiBearerAuth()
@Controller('admin/consults')
export class AdminConsultController {
  constructor(
    private readonly consultService: ConsultService,
  ) {}

  @Get()
  @ApiOperation({
    summary: '관리자 상담 목록 조회',
    description: '상담 신청 목록을 검색 조건과 페이지네이션으로 조회합니다.',
  })
  @ApiOkResponse({
    description: '상담 목록 조회 성공',
    type: ConsultListResponseDto,
  })
  async getConsults(@Query() query: GetConsultsQueryDto) {
    return this.consultService.getConsults(query);
  }
}

➕ 6-2. 주요 Decorator

Decorator	용도
`@ApiTags()`	API 그룹
`@ApiOperation()`	API 설명
`@ApiBearerAuth()`	Bearer Token 인증 표시
`@ApiOkResponse()`	200 응답 설명
`@ApiCreatedResponse()`	201 응답 설명
`@ApiBadRequestResponse()`	400 에러 설명
`@ApiForbiddenResponse()`	403 에러 설명
`@ApiQuery()`	Query Parameter 설명
`@ApiParam()`	Path Parameter 설명
`@ApiBody()`	Request Body 설명

API가 많아질수록 그룹을 잘 나누는 것이 중요합니다.

✅ 7. DTO 문서화

DTO에 @ApiProperty()를 붙이면 Swagger에서 request body 구조가 잘 보입니다.

➕ 7-1. CreateConsultDto 예시

export class CreateConsultDto {
  @ApiProperty({
    example: '홍길동',
    description: '신청자 이름',
  })
  @IsString()
  @MinLength(2)
  @MaxLength(20)
  name: string;

  @ApiProperty({
    example: '01012345678',
    description: '신청자 전화번호, 하이픈 없이 입력',
  })
  @IsString()
  @Matches(/^010\d{8}$/)
  phone: string;

  @ApiProperty({
    example: 15,
    description: '상담 신청 상품 ID',
  })
  @IsInt()
  productId: number;

  @ApiPropertyOptional({
    example: 'NAVER_AD',
    description: '유입 경로 코드',
  })
  @IsOptional()
  @IsString()
  source?: string;
}

➕ 7-2. 좋은 DTO 문서 기준

example이 현실적인 값이어야 합니다.
description이 운영 용어와 맞아야 합니다.
optional 필드는 @ApiPropertyOptional()을 사용합니다.
enum은 가능한 값이 보이게 합니다.
개인정보 예시는 실제 데이터가 아니라 가짜 데이터를 사용합니다.

✅ 8. Enum 문서화

상태값 API에서는 enum 문서화가 중요합니다.
프론트엔드와 관리자 화면에서 어떤 상태값을 표시하고 변경할 수 있는지 알아야 하기 때문입니다.

➕ 8-1. 상담 상태 enum 예시

export enum ConsultStatus {
  PENDING = 'PENDING',
  CALLING = 'CALLING',
  DONE = 'DONE',
  CANCELLED = 'CANCELLED',
}

➕ 8-2. DTO에서 enum 문서화

export class UpdateConsultStatusDto {
  @ApiProperty({
    enum: ConsultStatus,
    example: ConsultStatus.DONE,
    description: '변경할 상담 상태',
  })
  @IsEnum(ConsultStatus)
  status: ConsultStatus;

  @ApiPropertyOptional({
    example: '고객 상담 완료',
    description: '상태 변경 사유 또는 메모',
  })
  @IsOptional()
  @IsString()
  reason?: string;
}

➕ 8-3. 별도 문서에 적어야 하는 것

Swagger:
가능한 enum 값 표시

별도 정책 문서:
PENDING → CALLING 가능
CALLING → DONE 가능
DONE → PENDING 일반 관리자 불가
CANCELLED 이후 변경 제한

Swagger는 값 목록을 보여주는 데 강합니다.
상태 전이 규칙은 별도 내부 문서로 정리하는 것이 좋습니다.

✅ 9. Response DTO 설계

API 응답 구조도 DTO로 문서화하면 프론트엔드에서 이해하기 쉽습니다.
특히 목록 API, 페이지네이션, 관리자 테이블 응답은 명확해야 합니다.

➕ 9-1. 공통 응답 구조 예시

{
  "success": true,
  "data": {},
  "message": "요청이 성공했습니다."
}

➕ 9-2. 페이지네이션 응답 예시

{
  "success": true,
  "data": {
    "items": [],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 120,
      "totalPages": 6
    }
  }
}

➕ 9-3. Response DTO 예시

export class PaginationMetaDto {
  @ApiProperty({ example: 1 })
  page: number;

  @ApiProperty({ example: 20 })
  limit: number;

  @ApiProperty({ example: 120 })
  total: number;

  @ApiProperty({ example: 6 })
  totalPages: number;
}

export class ConsultListResponseDto {
  @ApiProperty({
    type: [ConsultItemDto],
  })
  items: ConsultItemDto[];

  @ApiProperty({
    type: PaginationMetaDto,
  })
  meta: PaginationMetaDto;
}

응답 구조를 문서화하면 프론트엔드에서 타입을 맞추기 쉽습니다.
응답 구조 변경이 breaking change인지 판단하기도 쉬워집니다.

✅ 10. 에러 응답 문서화

좋은 API 문서는 성공 응답뿐 아니라 실패 응답도 설명합니다.
실무에서는 에러 응답이 더 중요할 때가 많습니다.

➕ 10-1. 공통 에러 응답 예시

{
  "success": false,
  "error": {
    "code": "CONSULT_DUPLICATED",
    "message": "이미 신청된 정보입니다.",
    "statusCode": 409
  }
}

➕ 10-2. 에러 코드 문서 예시

HTTP Status	Error Code	의미
400	`VALIDATION_ERROR`	입력값 검증 실패
401	`UNAUTHORIZED`	로그인 필요
403	`FORBIDDEN`	권한 부족
404	`CONSULT_NOT_FOUND`	상담 신청 없음
409	`CONSULT_DUPLICATED`	중복 신청
500	`INTERNAL_SERVER_ERROR`	서버 오류

➕ 10-3. Swagger에 에러 응답 추가

@ApiBadRequestResponse({
  description: '입력값 검증 실패',
})
@ApiUnauthorizedResponse({
  description: '로그인이 필요합니다.',
})
@ApiForbiddenResponse({
  description: '권한이 없습니다.',
})
@ApiConflictResponse({
  description: '이미 신청된 정보입니다.',
})

프론트엔드는 에러 코드에 따라 사용자 메시지를 다르게 보여줄 수 있습니다.
QA는 예외 케이스를 테스트할 기준을 얻을 수 있습니다.

✅ 11. API 버전 관리

API가 커지면 버전 관리가 필요할 수 있습니다.
응답 구조를 갑자기 바꾸면 기존 프론트나 외부 연동이 깨질 수 있습니다.

➕ 11-1. 위험한 변경

기존:
GET /api/products 응답 data.items

변경:
GET /api/products 응답 products

결과:
기존 프론트에서 상품 목록 렌더링 실패

➕ 11-2. 버전 관리 방식

URL 버전:
GET /api/v1/products
GET /api/v2/products

Header 버전:
Accept: application/vnd.example.v2+json

기능 플래그:
관리자 일부에게만 새 응답 적용

➕ 11-3. 작은 서비스 기준

초기:
무리하게 v1/v2 나누기보다 하위 호환 유지

성장 후:
외부 연동 또는 앱 연동이 생기면 버전 관리 검토

현재 웹 프론트와 백엔드를 함께 관리한다면 하위 호환을 지키는 것부터 시작하면 됩니다.
외부 업체가 API를 쓰기 시작하면 버전 관리가 더 중요해집니다.

✅ 12. Postman Collection 관리

Swagger는 자동 문서화에 좋고, Postman은 실제 테스트 시나리오 관리에 좋습니다.
특히 로그인 → 토큰 저장 → 관리자 API 호출 흐름을 테스트하기 쉽습니다.

➕ 12-1. Postman에 넣으면 좋은 Collection

Auth
Consults
Admin Consults
Products
Orders
Banners
Export
Webhook
Notification
Health Check

➕ 12-2. Environment 변수

baseUrl=https://api.example.com
adminToken=...
consultId=123
productId=15

로컬, 개발, 운영 환경별 Environment를 나누면 테스트하기 편합니다.
운영 토큰이나 개인정보가 포함된 Collection은 공유에 주의해야 합니다.

✅ 13. 내부 개발 문서 구조

Swagger는 API 문서에 강하지만, 전체 운영 구조를 설명하기에는 부족합니다.
Notion, GitHub Wiki, Markdown 문서로 내부 개발 문서를 같이 관리하는 것이 좋습니다.

➕ 13-1. 추천 문서 구조

docs/
  architecture.md
  api-guidelines.md
  env.md
  deploy.md
  database.md
  migration.md
  runbook.md
  security.md
  queue-worker.md
  webhook.md
  release-notes.md

➕ 13-2. 각 문서 내용

문서	내용
`architecture.md`	전체 서버/DB/S3/CloudFront 구조
`api-guidelines.md`	API 설계 규칙, 응답 구조, 에러 코드
`env.md`	환경변수 목록과 설명
`deploy.md`	배포 순서, PM2/Docker 명령어
`database.md`	주요 테이블과 관계
`migration.md`	DB 변경 절차
`runbook.md`	장애 대응 절차
`security.md`	보안 체크리스트
`queue-worker.md`	Queue/Worker 구조
`webhook.md`	Webhook 수신/검증/재처리
`release-notes.md`	배포 기록

문서가 코드와 같이 Git에 있으면 변경 이력을 관리하기 좋습니다.
Notion에는 운영자가 보기 쉬운 형태로 요약본을 둘 수 있습니다.

✅ 14. API 설계 규칙 문서

API가 많아질수록 설계 규칙을 정해두는 것이 중요합니다.
규칙이 없으면 URL, 응답 구조, 에러 처리 방식이 기능마다 달라집니다.

➕ 14-1. API 설계 규칙 예시

## API 설계 규칙

### URL
- 고객 API: /api/...
- 관리자 API: /api/admin/...
- 복수 리소스 사용: /api/products, /api/consults
- 동작보다 리소스 중심으로 설계

### Response
```json
{
  "success": true,
  "data": {},
  "message": "요청이 성공했습니다."
}

Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "사용자에게 보여줄 메시지",
    "statusCode": 400
  }
}

Pagination

page 기본값: 1
limit 기본값: 20
limit 최대값: 100

Date

DB 저장은 UTC
관리자 화면 표시는 Asia/Seoul 기준


*   이런 규칙이 있으면 새 API를 만들 때 일관성이 생깁니다.
*   AI에게 작업을 시킬 때도 이 문서를 같이 주면 결과물이 훨씬 좋아집니다.

---

### ✅ 15. 환경변수 문서화

*   환경변수는 배포 장애와 보안 사고의 주요 원인입니다.
*   어떤 환경변수가 왜 필요한지 문서화해두면 배포 안정성이 좋아집니다.

#### ➕ 15-1. env 문서 예시

```md id="env-doc-example"
## 환경변수 목록

| 이름 | 필수 | 설명 | 예시 |
|---|---|---|---|
| NODE_ENV | Y | 실행 환경 | production |
| PORT | Y | API 서버 포트 | 3000 |
| DATABASE_URL | Y | PostgreSQL 연결 문자열 | postgresql://... |
| JWT_SECRET | Y | JWT 서명 Secret | 실제 값 문서화 금지 |
| REDIS_HOST | Y | Redis host | localhost |
| S3_BUCKET | Y | S3 버킷명 | togethermall-assets |
| KAKAO_API_KEY | Y | 알림톡 API Key | 실제 값 문서화 금지 |

주의사항

실제 Secret 값은 문서에 적지 않는다.
.env.example에는 구조만 남긴다.
운영 Secret은 서버 또는 Secret Manager에서 관리한다.


*   문서에는 실제 Secret 값을 절대 적지 않습니다.
*   “무슨 환경변수가 필요한지”와 “어디에 쓰는지”만 적습니다.

---

### ✅ 16. DB 문서화

*   DB 문서는 테이블 구조를 모두 복붙하는 것보다, 핵심 도메인과 관계를 설명하는 것이 중요합니다.

#### ➕ 16-1. DB 문서에 넣을 것

```txt id="db-doc-content"
주요 테이블 목적
테이블 간 관계
중요 enum 상태값
unique 제약
index 설계 의도
soft delete 여부
개인정보 포함 여부
운영에서 직접 수정하면 안 되는 테이블

➕ 16-2. 예시

## Consult

### 목적
고객 상담 신청 정보를 저장한다.

### 주요 필드
- id: 상담 신청 ID
- phone: 고객 전화번호
- productId: 신청 상품
- status: 상담 상태
- completedAt: 상담 완료 시간
- source: 유입 경로

### 관계
- ConsultStatusHistory와 1:N
- NotificationLog와 relatedType/relatedId로 연결
- ExportJob에서 조회 대상이 될 수 있음

### 제약
- phone + productId + eventId unique
- status + createdAt index

### 주의사항
- 전화번호는 개인정보
- 운영에서 hard delete 금지
- 상태 변경은 반드시 상태 변경 API를 통해 처리
``` id="mmocv2"

*   DB 문서에는 운영상 주의사항까지 같이 적는 것이 좋습니다.

---

### ✅ 17. Webhook 문서화

*   Webhook은 외부 서비스와 연결되기 때문에 문서화가 특히 중요합니다.
*   외부 이벤트가 어떻게 들어오고, 어떤 검증을 거쳐, 어떤 상태 변경을 하는지 명확해야 합니다.

#### ➕ 17-1. Webhook 문서 항목

```txt id="webhook-doc-content"
Webhook URL
Provider
Event Type
Signature 검증 방식
Raw Body 필요 여부
중복 eventId 처리
상태 전이 규칙
실패 시 재처리 방식
로그 테이블
수동 재처리 방법

➕ 17-2. 예시

## Payment Webhook

### URL
POST /api/webhooks/payment

### 인증/검증
- X-Signature 헤더 기반 HMAC 검증
- Raw Body 기준으로 서명 검증
- provider + eventId unique 제약

### 처리 흐름
1. Signature 검증
2. WebhookEvent 저장
3. 중복 eventId 확인
4. orderId 매핑
5. 상태 전이 가능 여부 확인
6. 주문 상태 변경
7. 후속 알림 Job 등록

### 실패 처리
- 검증 실패: 401
- 중복 이벤트: 200 OK
- 처리 실패: WebhookEvent FAILED 저장
- 재처리: 관리자 Webhook 실패 목록에서 수동 재처리
``` id="s5wmxg"

*   Webhook은 장애가 났을 때 문서가 없으면 추적이 매우 어렵습니다.

---

### ✅ 18. Queue/Worker 문서화

*   Queue와 Worker는 API 요청 밖에서 돌아가기 때문에 문서가 없으면 운영자가 상태를 이해하기 어렵습니다.

#### ➕ 18-1. 문서화할 것

```txt id="queue-doc-content"
Queue 이름
Job 이름
Producer 위치
Worker 위치
Job data 구조
재시도 횟수
backoff 기준
멱등성 키
실패 로그 저장 위치
수동 재처리 방법

➕ 18-2. 예시

## Notification Queue

### Queue Name
notification

### Job: send-consult-created-alimtalk

### 등록 시점
상담 신청 생성 후 NotificationProducer에서 등록

### Job Data
```json
{
  "consultId": 123
}

재시도

attempts: 3
backoff: exponential, 3초 시작

멱등성

NotificationLog.idempotencyKey = notification:consult:{consultId}:created
이미 SUCCESS인 경우 중복 발송하지 않음

실패 처리

NotificationLog FAILED 저장
JobFailureLog 저장
관리자 알림 실패 목록에서 재처리 가능


*   Queue 문서는 Worker 장애 대응, 배포 순서, 재처리 기능 설계에 바로 도움이 됩니다.

---

### ✅ 19. 문서와 코드의 불일치 문제

*   문서화의 가장 큰 문제는 시간이 지나면 문서와 실제 코드가 달라진다는 점입니다.
*   오래된 문서는 없는 문서보다 더 위험할 수 있습니다.

#### ➕ 19-1. 문서가 낡는 이유

```txt id="doc-stale-reason"
API 응답 구조 변경
DB 컬럼 추가/삭제
환경변수 추가
Queue Job 이름 변경
권한 정책 변경
Webhook payload 변경
배포 방식 변경

➕ 19-2. 방지 방법

API 변경 PR에 문서 수정 포함
Swagger로 DTO/Controller 문서 자동화
release note에 변경사항 기록
환경변수 추가 시 env.md 업데이트
DB migration 시 migration.md 업데이트
Runbook은 장애 후 바로 수정

문서는 개발 프로세스 안에 넣어야 유지됩니다.
“나중에 정리”는 보통 안 됩니다.

✅ 20. 릴리즈 노트와 변경 로그

API 문서와 별개로, 이번 배포에서 무엇이 바뀌었는지 기록하는 릴리즈 노트가 필요합니다.
장애 대응과 운영 커뮤니케이션에 도움이 됩니다.

➕ 20-1. 릴리즈 노트 예시

## Release 2026-07-14

### API 변경
- POST /api/consults 중복 신청 시 409 Conflict 응답 추가
- GET /api/admin/consults 응답에 completedAt 필드 추가

### DB 변경
- Consult.completedAt 컬럼 추가
- ConsultStatusHistory index 추가

### Worker 변경
- notification queue에 send-consult-created-alimtalk jobId 추가

### 환경변수
- 없음

### 운영 확인
- 상담 신청 정상
- 관리자 목록 정상
- 알림톡 Job 정상

릴리즈 노트는 “무슨 일이 바뀌었는지”를 시간순으로 남기는 운영 기록입니다.
나중에 장애가 생기면 특정 날짜 배포 변경을 바로 확인할 수 있습니다.

✅ 21. AI와 문서화 자동화

AI는 개발 문서 초안 작성에 매우 유용합니다.
하지만 AI에게 문서를 맡길 때는 실제 코드, API 응답, DB 모델, 운영 정책을 같이 제공해야 합니다.

➕ 21-1. 좋은 활용 방식

코드/DTO/Prisma 모델/운영 정책 제공
  ↓
AI가 초안 작성
  ↓
개발자가 실제 코드와 비교 검수
  ↓
Notion/GitHub docs에 반영

➕ 21-2. AI에게 맡기기 좋은 문서

API 설명 초안
Runbook 초안
릴리즈 노트 초안
DB 테이블 설명
Queue/Worker 흐름 문서
Webhook 처리 흐름 문서
배포 체크리스트
장애 기록 정리

➕ 21-3. 주의할 점

AI가 실제 코드에 없는 필드를 만들어낼 수 있습니다.
API 응답 구조를 추측할 수 있습니다.
보안 정책을 일반론으로만 작성할 수 있습니다.
문서 초안은 반드시 실제 코드와 비교해야 합니다.

✅ 22. 실무 체크리스트

➕ 22-1. API 문서 체크리스트

각 API의 Method/URL이 정리되어 있는가?
인증 필요 여부가 표시되어 있는가?
권한과 데이터 범위 조건이 적혀 있는가?
Query Parameter와 Request Body가 설명되어 있는가?
Response Body 예시가 있는가?
Error Response와 에러 코드가 정리되어 있는가?
상태값 enum과 상태 전이 규칙이 설명되어 있는가?
개인정보/중복 요청/Rate Limit 같은 주의사항이 있는가?

➕ 22-2. Swagger 체크리스트

@ApiTags()로 API 그룹이 나뉘어 있는가?
@ApiOperation() 설명이 실제 기능과 맞는가?
DTO에 @ApiProperty() 예시가 있는가?
인증 API에 @ApiBearerAuth()가 붙어 있는가?
주요 에러 응답이 문서화되어 있는가?
운영 환경에서 Swagger 접근이 제한되어 있는가?
실제 API 응답 구조와 문서가 일치하는가?
테스트용/내부용 API가 운영 Swagger에 노출되지 않는가?

➕ 22-3. 내부 문서 체크리스트

아키텍처 문서가 있는가?
환경변수 문서가 있는가?
배포 절차 문서가 있는가?
DB 주요 테이블 문서가 있는가?
Migration/Backfill 문서가 있는가?
Queue/Worker 문서가 있는가?
Webhook 문서가 있는가?
Runbook과 장애 기록 템플릿이 있는가?
보안 체크리스트가 있는가?
릴리즈 노트가 남는가?

✅ 23. AI를 활용해 API/운영 문서를 만들 때 질문법

AI에게 문서화를 요청할 때는 단순히 “문서 만들어줘”보다, 실제 프로젝트 구조와 원하는 문서 목적을 같이 알려주는 것이 좋습니다.

➕ 23-1. 좋은 질문 예시

NestJS + Prisma 기반 온라인 휴대폰 판매몰 백엔드의 API/운영 문서를 정리하고 싶어.

상황:
1. 고객 API에는 상품 목록, 상품 상세, 상담 신청이 있음
2. 관리자 API에는 상담 관리, 주문 관리, 상품 관리, 배너 관리, 엑셀 다운로드가 있음
3. JWT 기반 관리자 인증을 사용함
4. 역할은 SUPER_ADMIN, ADMIN, MANAGER, VIEWER가 있음
5. 상담 상태는 PENDING, CALLING, DONE, CANCELLED가 있음
6. Queue Worker는 알림톡, Export, Webhook 후속 처리를 담당함
7. DB는 Prisma schema로 관리하고, 운영 migration은 migrate deploy를 사용함
8. Swagger를 붙이고, 별도 docs 폴더에 운영 문서도 만들고 싶음

요청:
- Swagger 설정 방식
- Controller/DTO 문서화 예시
- API 응답/에러 코드 규칙
- 상태값 enum 문서화 기준
- docs 폴더 구조
- env 문서 템플릿
- DB 문서 템플릿
- Webhook 문서 템플릿
- Queue/Worker 문서 템플릿
- 릴리즈 노트 템플릿
- 문서 최신화 체크리스트
를 실무 기준으로 정리해줘.

➕ 23-2. AI 답변 검증 기준

Swagger만으로 모든 문서가 끝난다고 말하지 않는가?
인증/권한/에러 응답/상태 전이 규칙을 문서화하라고 하는가?
운영 Swagger 접근 제한을 언급하는가?
환경변수 문서에 실제 Secret 값을 적지 말라고 하는가?
DB 문서에 주요 관계와 운영 주의사항을 포함하는가?
Webhook/Queue/Worker 문서를 별도로 정리하는가?
릴리즈 노트와 변경 로그를 권장하는가?
문서와 코드 불일치 문제를 방지하는 방법을 제안하는가?

📌 요약

API 문서화는 API의 요청 방식, 응답 구조, 인증, 권한, 에러 코드, 사용 예시를 정리하는 작업입니다.
좋은 API 문서는 URL 목록만 있는 것이 아니라 Request, Response, Error, 권한, 상태값, 주의사항까지 포함해야 합니다.
Swagger는 NestJS Controller/DTO 기반으로 API 문서를 자동 생성하고 간단한 테스트까지 할 수 있게 해주는 도구입니다.
운영 환경에서 Swagger를 그대로 공개하면 관리자 API 구조와 내부 정보가 노출될 수 있으므로 비활성화하거나 접근 제한을 걸어야 합니다.
DTO에는 @ApiProperty()와 현실적인 example을 추가하고, enum 상태값은 Swagger와 별도 정책 문서에서 함께 관리하는 것이 좋습니다.
API 응답 구조와 에러 코드 규칙을 통일하면 프론트엔드 개발, QA, 장애 대응이 쉬워집니다.
Swagger는 API 문서에는 강하지만, 배포, DB, Migration, Queue, Webhook, Runbook, 보안 정책은 별도 내부 문서로 관리해야 합니다.
환경변수 문서에는 실제 Secret 값을 적지 말고, 어떤 값이 왜 필요한지만 정리해야 합니다.
문서는 시간이 지나면 코드와 달라질 수 있으므로 API 변경, migration, 환경변수 추가, Queue 변경, 배포 변경 시 문서 수정도 함께 진행해야 합니다.
AI는 문서 초안 작성에 매우 유용하지만, 실제 코드와 응답 구조를 기준으로 반드시 검수해야 합니다.

juni

이전 포스트

TIL - 20260713

다음 포스트

TIL - 20260714

TIL

0714 백엔드 실무 심화 (21/N): API 문서화, Swagger와 내부 개발 문서 관리

✅ 1. API 문서화란 무엇인가?

➕ 1-1. API 문서가 필요한 이유

✅ 2. 좋은 API 문서의 기준

➕ 2-1. 좋은 API 문서에 필요한 요소

➕ 2-2. 나쁜 문서 예시

➕ 2-3. 좋은 문서 예시

Response

Error

주의사항

➕ 3-1. Swagger의 장점

➕ 3-2. Swagger의 한계

✅ 4. NestJS Swagger 기본 설정

➕ 4-1. 설치

➕ 4-2. main.ts 설정 예시

➕ 4-3. 접근 URL

✅ 5. Swagger 보안 설정

➕ 5-1. 운영에서 주의할 점

➕ 5-2. 권장 방식

➕ 5-3. 환경별 Swagger 활성화 예시

✅ 6. Controller 문서화

➕ 6-1. Controller 예시

➕ 6-2. 주요 Decorator

✅ 7. DTO 문서화

➕ 7-1. CreateConsultDto 예시

➕ 7-2. 좋은 DTO 문서 기준

✅ 8. Enum 문서화

➕ 8-1. 상담 상태 enum 예시

➕ 8-2. DTO에서 enum 문서화

➕ 8-3. 별도 문서에 적어야 하는 것

✅ 9. Response DTO 설계

➕ 9-1. 공통 응답 구조 예시

➕ 9-2. 페이지네이션 응답 예시

➕ 9-3. Response DTO 예시

✅ 10. 에러 응답 문서화

➕ 10-1. 공통 에러 응답 예시

➕ 10-2. 에러 코드 문서 예시

➕ 10-3. Swagger에 에러 응답 추가

✅ 11. API 버전 관리

➕ 11-1. 위험한 변경

➕ 11-2. 버전 관리 방식

➕ 11-3. 작은 서비스 기준

✅ 12. Postman Collection 관리

➕ 12-1. Postman에 넣으면 좋은 Collection

➕ 12-2. Environment 변수

✅ 13. 내부 개발 문서 구조

➕ 13-1. 추천 문서 구조

➕ 13-2. 각 문서 내용

✅ 14. API 설계 규칙 문서

➕ 14-1. API 설계 규칙 예시

Error

Pagination

Date

주의사항

➕ 16-2. 예시

➕ 17-2. 예시

➕ 18-2. 예시

재시도

멱등성

실패 처리

➕ 19-2. 방지 방법

✅ 20. 릴리즈 노트와 변경 로그

➕ 20-1. 릴리즈 노트 예시

✅ 21. AI와 문서화 자동화

➕ 21-1. 좋은 활용 방식

➕ 21-2. AI에게 맡기기 좋은 문서

➕ 21-3. 주의할 점

✅ 22. 실무 체크리스트

➕ 22-1. API 문서 체크리스트

➕ 22-2. Swagger 체크리스트

➕ 22-3. 내부 문서 체크리스트

✅ 23. AI를 활용해 API/운영 문서를 만들 때 질문법

➕ 23-1. 좋은 질문 예시

➕ 23-2. AI 답변 검증 기준

📌 요약

TIL - 20260713

TIL - 20260715

0개의 댓글