Swagger란?
Swagger는 RESTful API를 설계, 빌드, 문서화하고 시각화하는 데 사용되는 강력한 도구입니다. 이는 개발자들이 API를 이해하고 테스트하며, 더욱 효율적으로 작업할 수 있게 도와줍니다.
Swagger의 주요 특징:
- 자동 문서 생성: Swagger를 사용하면 코드에서 API 엔드포인트, 요청 및 응답 형식을 자동으로 추출하여 API 문서를 생성할 수 있습니다.
- 시각화된 인터페이스: Swagger는 시각적으로 풍부한 사용자 인터페이스를 제공하여 개발자들이 API를 더 쉽게 이해하고 테스트할 수 있게 합니다.
- 인터랙티브한 테스트 환경: Swagger UI를 통해 API 엔드포인트에 대한 테스트를 쉽게 수행할 수 있습니다.
NestJS에서 Swagger 사용하기
@nestjs/swagger 패키지 설치
먼저 관련 패키지를 설치합니다.
npm install --save @nestjs/swagger swagger-ui-expressSwagger 설정
- DocumentBuilder를 사용하여 Swagger 옵션 구성:
const options = new DocumentBuilder()
.setTitle('NestJS API Docs')
.setDescription('NestJS API description')
.setVersion('1.0.0')
.build();DocumentBuilder를 생성하고, API 문서에 표시될 제목, 설명, 및 버전을 설정합니다.
- SwaggerModule.createDocument로 API 문서 생성:
const document = SwaggerModule.createDocument(app, options);SwaggerModule.createDocument 함수를 사용하여 NestJS 애플리케이션과 Swagger 옵션을 이용하여 API 문서를 생성합니다.
- SwaggerModule.setup으로 Swagger UI 설정:
SwaggerModule.setup('api-docs', app, document);SwaggerModule.setup 함수를 호출하여 Swagger UI를 설정합니다. 여기서 'api-docs'는 Swagger UI의 기본 경로입니다. 이 경로를 통해 Swagger UI에 액세스할 수 있습니다.
- 설정된 함수를 NestJS 애플리케이션에 적용:
export function setupSwagger(app: INestApplication): void {
// ... (위의 코드)
// NestJS 애플리케이션에 Swagger를 적용
SwaggerModule.setup('api-docs', app, document);
}최종적으로, setupSwagger 함수를 내보내고, 이 함수를 main.ts 또는 app.module.ts 파일에 추가하여 Swagger를 적용할 수 있습니다.
swagger 추가 옵션 설정
컨트롤러 별 태그 분류
NestJS의 @ApiTags 데코레이터를 Swagger와 함께 사용하면 API 문서의 다양한 부분을 분류하고 구성하는 방법을 제공합니다.
1. @ApiTags 데코레이터:
@ApiTags('reservation API')이 데코레이터는 전체 컨트롤러에 태그를 할당하는 데 사용됩니다. 이 경우 컨트롤러에는 'festival API'라는 태그가 지정되어 Swagger UI에서 API의 다양한 부분을 분류하고 구성하는 방법을 제공합니다.
- @ApiOperation 데코레이터:
@Post('/register/:festivalId')
@ApiOperation({
summary: '축제예약 api',
description: description: '축제예약'
})@ApiOperation은 메소드에 적용됩니다. 작업에 대한 메타데이터(API 엔드포인트)를 제공합니다. '요약'은 간단한 설명이고, '설명'은 작업에 대한 자세한 내용을 제공합니다.
- @ApiCreatedResponse 데코레이터:
@ApiCreatedResponse({
description: '축제 예약',
type: ReservationEntity
})@ApiCreatedResponse는 주석이 달린 작업에 대한 성공적인 HTTP 응답을 문서화하는 데 사용됩니다. 이 경우 엔드포인트가 '축제 예약' 설명과 함께 응답을 반환할 수 있으며, 응답 페이로드는 'ReservationEntity' 유형이어야 함을 나타냅니다.
- @ApiBody 데코레이터:
@ApiBody({ type: CreateReservationDto })요청 본문에 대한 Swagger 문서에 DTO(데이터 전송 개체) 부분을 포함하기 위해 @ApiBody 데코레이터를 사용할 수 있습니다. 이 데코레이터를 사용하면 DTO 구조에 대한 세부 정보가 포함된 요청 본문의 스키마를 지정할 수 있습니다.
- @ApiBearerAuth 데코레이터:
현재 이 api는 인증 관련 설정이 있는 nestjs컨트롤러입니다.
이러한 경우 Swagger의 @ApiBearerAuth 데코레이터를 사용할 수 있습니다.
@UseGuards(JwtAuthGuard)
@Controller('reservation')
@ApiTags('reservation API')
@ApiBearerAuth()
export class ReservationController {
...
}
@ApiProperty 데코레이터:
@PrimaryGeneratedColumn('uuid')
@ApiProperty({ description: 'id' })
id: string;
@Column({ nullable: true, type: 'date' })
@ApiProperty({ description: '예약 날짜' })
date: Date;
@Column({ nullable: true, type: 'text' })
@ApiProperty({ description: '축제관련 메모' })
memo: string;@ApiProperty({ description: 'id' }): 'id' 필드에 대한 설명을 제공합니다.
@ApiProperty({ description: '예약 날짜' }): 'date' 필드에 대한 설명을 제공합니다.
@ApiProperty({ description: '축제관련 메모' }): 'memo' 필드에 대한 설명을 제공합니다.
이렇게 추가된 Swagger 관련 코드는 Swagger UI에서 API 문서를 생성할 때 각 필드에 대한 설명을 표시하고, 필드의 형식을 정의하는 데 도움을 줍니다.
NestJS에서 자주 사용되는 Swagger 데코레이터 목록
@ApiExcludeEndpoint() - Swagger 문서에서 특정 엔드포인트를 제외합니다.
@ApiExtraModels() - Swagger에 포함될 추가 모델을 지정합니다.
@ApiHeader() - Swagger에서 작업의 헤더 매개변수를 설명합니다.
@ApiParam() - Swagger에서 작업의 매개변수를 설명합니다.
@ApiResponseProperty() - 모델의 속성을 장식하여 Swagger에 대한 추가 세부정보를 제공합니다.
@ApiQuery() - Swagger에서 작업의 쿼리 매개변수를 설명합니다.
@ApiQuery({ isArray: true, type: String }) - 쿼리 매개변수가 배열임을 지정하고 해당 유형을 정의합니다.
@ApiOAuth2() - API에 대한 OAuth2 인증 세부 정보를 지정합니다.
@ApiUseTags() - Swagger 문서에 사용할 추가 태그를 지정합니다.
