Swagger로 API 문서는 어떻게 생성하나요?

Question

Accepted Answer

NestJS는 `@nestjs/swagger`를 통해 **Swagger/OpenAPI**와 통합되어 코드 — controller, 라우트, DTO, decorator — 로부터 **대화형 API 문서를 자동 생성**합니다. 개발자가 엔드포인트를 탐색하고 테스트할 수 있는 브라우저 가능한 UI를 생성하며, 코드와 동기화 상태를 유지합니다.

## Swagger 설정

```ts
// main.ts
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

const config = new DocumentBuilder()
  .setTitle("Users API")
  .setDescription("The users API documentation")
  .setVersion("1.0")
  .addBearerAuth()                       // JWT 인증 문서화
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api/docs", app, document);   // /api/docs에서 UI 제공
```

몇 줄로 Swagger가 앱을 스캔하고 `/api/docs`에서 대화형 문서를 제공합니다 — 라우트, 파라미터, DTO를 자동으로 반영합니다.

## DTO와 응답 문서화

```ts
export class CreateUserDto {
  @ApiProperty({ example: "ann@example.com", description: "User email" })
  email: string;

@ApiProperty({ minLength: 8 })
  password: string;

@ApiPropertyOptional()                 // 문서에서 선택적 필드
  age?: number;
}
```

`@ApiProperty` decorator는 DTO 필드에 설명, 예시, 제약을 추가하여 생성된 스키마를 풍부하게 합니다. (많은 부분이 TypeScript 타입과 `class-validator` decorator에서 자동으로 추론되며 — `CLI 플러그인`은 이 보일러플레이트조차 줄일 수 있습니다.)

## 엔드포인트 문서화

```ts
@ApiTags("users")                        // UI에서 엔드포인트 그룹화
@Controller("users")
export class UsersController {
  @Post()
  @ApiOperation({ summary: "Create a user" })
  @ApiResponse({ status: 201, description: "User created", type: User })
  @ApiResponse({ status: 400, description: "Invalid input" })
  create(@Body() dto: CreateUserDto) {}
}
```

`@ApiTags`, `@ApiOperation`, `@ApiResponse` 같은 decorator는 설명을 추가하고, 엔드포인트를 그룹화하고, 가능한 응답을 문서화합니다.

## 얻는 것

```text
✓ 대화형 UI (Swagger UI) — 브라우저에서 엔드포인트 탐색, 읽기, 테스트
✓ 자동 생성, 항상 코드와 동기화 (유지할 별도 문서 없음)
✓ OpenAPI 스펙 (JSON) — 클라이언트 SDK 생성, 계약 테스트 등에 사용 가능
✓ 요청/응답 스키마, 검증 규칙, 인증 요구사항 모두 문서화
```

## 왜 중요한가

API 문서는 다른 사람이 소비하는 모든 API에 필수적입니다 — 프론트엔드 팀, 모바일 앱, 서드파티 통합자, 또는 미래의 자신까지 — 그리고 NestJS의 Swagger 통합은 고품질 문서를 만드는 것을 놀랍도록 쉽고 안정적으로 만듭니다.

핵심 이점은 문서가 **코드로부터 자동 생성된다**는 것입니다(controller, 라우트, DTO, decorator) — 그래서 손으로 쓴 문서가 필연적으로 그러는 것처럼 낡아지는 대신 실제 구현과 **동기화**를 유지합니다.

좋은 API 문서가 개발자 경험을 극적으로 개선하고 통합 마찰을 줄이므로 이를 이해하는 것이 가치가 있습니다: 대화형 **Swagger UI**는 소비자가 브라우저에서 엔드포인트를 직접 탐색하고 *테스트*하게 하며, 생성된 **OpenAPI 스펙**은 클라이언트 SDK 생성과 계약 테스트를 이끌 수 있습니다.

Swagger를 설정하고, decorator(`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`)로 문서를 풍부하게 하고, 인증을 문서화하는 방법을 아는 것은 실무적이고 자주 필요한 지식입니다 — 잘 문서화된 API는 전문적 표준이자 양질의 백엔드 작업의 특징입니다.

NestJS가 decorator/DTO 구조를 활용하여 그렇게 많은 것을 자동으로 생성하므로(최소한의 추가 노력으로), 훌륭한 문서를 갖지 않을 변명이 거의 없으며, 이를 실제 NestJS 프로젝트에서 중요하고 가치가 높은 능력으로 만듭니다.