| 서론
안녕하세요 팡일입니다.
오늘은 Nest.js에서 API를 보다 효율적으로 관리할 수 있도록 도와주는 Swagger 설정 및 활용 방법에 대해 정리해보려고 합니다.
백엔드 개발을 하다 보면 API를 만들고 끝나는 것이 아니라, 문서화하고,*테스트하고, 협업하는 과정이 매우 중요하다는 것을 느끼게 됩니다. 특히 프론트엔드와 협업할 때 API 스펙이 명확하지 않으면 커뮤니케이션 비용이 크게 증가하게 되는데요? 이때 Swagger를 활용하면 코드만으로 API 문서를 자동 생성하고, 직접 테스트까지 가능해집니다.
이번 글에서는 Swagger가 무엇인지부터 Nest.js에서 실제로 적용하는 방법, 그리고 장단점까지 전체 흐름을 한 번에 정리해보겠습니다.
| Swagger란?
API를 설계하고 문서화하며 테스트할 수 있도록 도와주는 API 문서화 도구입니다.
특히 OpenAP Specification(OAS)이라는 표준을 사용하여 RESTful API를 정의하는 데 사용됩니다.
OAS란?
API의 구조를 언어에 구애받지 않는 형식(JSON 또는 YAML)으로 설명하기 위한 규격이다. JSON과 YAML은 데이터를 저장하고 전송하는 데 사용되는 텍스트 기반 형식이기 때문에, 특정 프로그래밍 언어에 종속되지 않는다.
쉽게 말해, NestJS에서 만든 API 엔드포인트, 요청/응답 데이터 구조, 인증 밥업 등을 표준화된 방식으로 정의하고, 이를 상호 작용 가능한 웹 인터페이스로 자동 생성해주는 도구입니다.
따라서, Swagger 도구들은 OpenAPI Specification를 기반으로 작동합니다.
| Swaager 장단점
1) 장점
- 코드에 데코레이터만 추가하면 실행 가능한 최신 API 문서가 자동으로 생성됩니다.
→ 코드가 변경되면 문서도 자동으로 업데이트되어 수동 문서화 작업이 필요 없습니다. - Swagger UI를 통해 브라우저에서 직접 API 요청을 보내고 응답을 확인할 수 있습니다.
→ Postman 같은 별도 도구 없이도 기본적인 API 테스트가 가능합니다. - 프론트엔드 개발자가 최신 API 스펙을 바로 확인할 수 있어
→ 프론트-백엔드 간 통합 및 커뮤니케이션 오류를 줄여줍니다. - OpenAPI Specification을 따르기 때문에
→ 다른 개발 도구와도 쉽게 연동할 수 있습니다.
2) 단점
- 문서화를 위해 실제 비즈니스 로직 코드에 많은 데코레이터를 추가해야 합니다.
→ 코드가 장황해지고 가독성이 떨어질 수 있습니다. - 간단한 API라도 정확한 문서를 위해
→ DTO, 파라미터, 응답 등에 @ApiProperty(), @ApiResponse() 등을 꼼꼼히 작성해야 하므로
→ 초기 작성 비용이 증가합니다. - 운영 환경(Production)에서 Swagger 문서 페이지(/api/docs)를 그대로 노출하면
→ 보안 이슈가 발생할 수 있습니다.
→ 따라서 로그인, IP 제한 등 접근 제어가 필요합니다.
| Swagger 전용 모듈 설치하기
1) 명령어로 설치하기
먼저 Swagger 관련 패키지를 설치합니다.
npm install --save @nestjs/swagger
해당 패키지는 Nest.js에서 Swagger 문서를 생성하기 위한 핵심 라이브러리입니다.
2) main.ts 수정하기
해당 패키지는 Nest.js에서 Swagger 문서를 생성하기 위한 핵심 라이브러리입니다.
NestJS 해당 공식 문서에 있는 Bootstrap을 사용하는 것을 추천드립니다.
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app/app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
// 1. Swagger 문서의 기본 정보 설정
const config = new DocumentBuilder()
.setTitle('First NestJS Swagger')
.setDescription('NestJS를 사용한 백엔드 API 설명')
.setVersion('1.0')
.build();
// 2. Swagger 문서 생성 함수 정의
const documentFactory = () => SwaggerModule.createDocument(app, config);
// 3. Swagger UI 엔드포인트 설정
SwaggerModule.setup('api', app, documentFactory);
await app.listen(process.env.PORT ?? 4000);
}
bootstrap();- DocumentBuilder
→ Swagger 문서의 기본 정보(제목, 설명, 버전 등)를 설정 - SwaggerModule.createDocument()
→ 현재 애플리케이션을 기반으로 API 문서를 생성 - SwaggerModule.setup('api', app, document)
→ /api 경로에서 Swagger UI 제공
| Swagger 관련 데코레이션
실제 API를 문서화하기 위해 Controller와 DTO에 @nestjs/swagger에서 제공하는 데코레이터를 사용할 수 있습니다.
이를 통해 API의 구조, 요청/응답 형태, 설명 등을 자동으로 문서화할 수 있습니다.
| 데코레이터 | 설명 |
| @ApiTags() | 컨트롤러 레벨에 적용하여 API 그룹을 지정합니다. (예: 'users', 'boards') |
| @ApiOperation() | 특정 라우트(메서드)에 대한 설명을 추가합니다. |
| @ApiBody() | 요청 본문(body)에 대한 정보를 명시합니다. |
| @ApiParam() | 경로 파라미터(path parameter)에 대한 정보를 명시합니다. |
| @ApiQuery() | 쿼리 파라미터(query parameter)에 대한 정보를 명시합니다. |
| @ApiResponse() | HTTP 응답 코드(상태 코드)별 응답 스키마를 정의합니다. |
| @ApiProperty() | DTO 클래스의 필드(속성)에 대한 설명, 타입, 필수 여부 등을 명시합니다. |
이렇게 데코레이터를 추가하는 것만으로, NestJS는 애플리케이션 실행 시, 이 메타데이터를 읽어 완전한 Swagger JSON/YAML 문서를 자동생성하고, 이를 Swagger UI로 보여줍니다.
1) 실제 예시
코드 보기
import {
Body,
Controller,
Delete,
Get,
Param,
Post,
Put,
} from '@nestjs/common';
import { BoardsService } from './boards.service';
import type { Board } from './boards.type';
import {
ApiTags,
ApiOperation,
ApiParam,
ApiBody,
ApiResponse,
} from '@nestjs/swagger';
@ApiTags('board') // Swagger에서 API 그룹화
@Controller('board')
export class BoardsController {
constructor(private readonly boardsService: BoardsService) {}
/**
* 전체 게시글 조회
*/
@Get()
@ApiOperation({ summary: '전체 게시글 조회' })
@ApiResponse({
status: 200,
description: '게시글 목록 반환',
})
findAll(): Board[] {
return this.boardsService.findAll();
}
/**
* 게시글 단건 조회
*/
@Get(':id')
@ApiOperation({ summary: '게시글 단건 조회' })
@ApiParam({
name: 'id',
description: '게시글 ID',
example: 1,
})
@ApiResponse({
status: 200,
description: '게시글 반환',
})
@ApiResponse({
status: 404,
description: '해당 게시글이 존재하지 않음',
})
findOne(@Param('id') id: number): Board {
return this.boardsService.findOne(Number(id));
}
/**
* 게시글 생성
*/
@Post()
@ApiOperation({ summary: '게시글 생성' })
@ApiBody({
schema: {
example: {
title: '게시글 제목',
content: '게시글 내용',
},
},
})
@ApiResponse({
status: 201,
description: '게시글 생성 완료',
})
create(@Body() data: any) {
return this.boardsService.create(data);
}
/**
* 게시글 수정
*/
@Put(':id')
@ApiOperation({ summary: '게시글 수정' })
@ApiParam({
name: 'id',
description: '수정할 게시글 ID',
example: 1,
})
@ApiBody({
schema: {
example: {
title: '수정된 제목',
content: '수정된 내용',
},
},
})
@ApiResponse({
status: 200,
description: '게시글 수정 완료',
})
@ApiResponse({
status: 404,
description: '해당 게시글이 존재하지 않음',
})
update(@Param('id') id: number, @Body() data: any): Board {
return this.boardsService.update(Number(id), data);
}
/**
* 게시글 삭제
*/
@Delete(':id')
@ApiOperation({ summary: '게시글 삭제' })
@ApiParam({
name: 'id',
description: '삭제할 게시글 ID',
example: 1,
})
@ApiResponse({
status: 200,
description: '게시글 삭제 완료',
})
@ApiResponse({
status: 404,
description: '해당 게시글이 존재하지 않음',
})
delete(@Param('id') id: number): Board[] {
return this.boardsService.delete(Number(id));
}
}
| 실제 화면
Swagger 설정을 완료한 후 서버를 실행하면 브라우저에서 아래 주소로 접속할 수 있습니다.
http://localhost:4000/api
해당 페이지에서는 다음과 같은 기능을 확인할 수 있습니다.
- 등록된 API 목록을 한눈에 확인 가능
- 각 API의 요청/응답 구조 확인
- 파라미터 및 Request Body 확인
- 직접 API 요청 실행 (Try it out 기능)
| 결론
이번 글에서는 Swagger를 활용하여 Nest.js API를 문서화하고 테스트하는 방법을 정리해보았습니다.
Swagger를 적용하면서 느낀 가장 큰 장점은 코드 기반으로 문서가 자동 생성되고 항상 최신 상태를 유지한다는 점이었습니다.
또한 브라우저에서 직접 API를 테스트할 수 있기 때문에 개발 속도뿐만 아니라 협업 효율도 크게 향상된다는 점이 인상적이었습니다.
물론 데코레이터를 추가해야 하는 번거로움이나 운영 환경에서의 보안 고려사항도 있지만, 그럼에도 불구하고 얻는 이점이 훨씬 크다고 느꼈습니다.
앞으로는 DTO와 Validation을 함께 적용하여 보다 실제 서비스에 가까운 API 문서 구조로 확장해보려고 합니다.
'💻 개발 > 🌸 NestJS' 카테고리의 다른 글
| [NestJS] DTO와 유효성 검사 (0) | 2026.03.27 |
|---|---|
| [NestJS] 데코레이터 CRUD 이해하기 (0) | 2026.03.27 |
| [NestJS] NestJS 기본 구조부터 CRUD까지 완벽 정리 (초보자 가이드) (0) | 2026.03.27 |