[NestJS] Swagger 설치 및 적용

Swagger

API를 따로 작성할 필요없이 코드 기반으로 API를 문서로 자동화해주는 도구이다

API와 코드를 따로 작성하면서 빼먹고 놓치는 부분이 많았는데,

Swagger를 통해서 코드를 수정하면서 API를 같이 수정할 수 있다는 것이 큰 장점이다.

 

---

0. Swagger 설치

NestJS v9 이상 부터는 @nesjs/swagger fastify-swagger 모듈을 설치하면 된다

npm install --save @nestjs/swagger

 

 

1. swagger 파일 생성

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

export function setupSwagger(app: INestApplication): void {
  const options = new DocumentBuilder()
    .setTitle('NestJS API Docs')
    .setDescription('NestJS API description')
    .setVersion('1.0.0')
    .build();

  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api-docs', app, document);
}

• SwaggerModule의 createDocument 메서드로 문서를 생성한다
• SwaggerModule의 setup메서드의 첫번째 인자가 url 경로가 된다 -> "http://localhost:3000/api-docs"

 

 

2. main.ts에 swagger 적용하기

import { setupSwagger } from 'src/util/swagger';

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

  setupSwagger(app);

  // ...
}
bootstrap();

 

 

3. api-docs 경로로 접속하기

• 코드 기반으로 API 문서가 작성되었다.

• 다만 아직 다른 설정을 하지 않아서 내용은 비어있다.

 

4. Controller에서 API 문서 설명 추가하기

import { ApiTags, ApiOperation, ApiCreatedResponse } from '@nestjs/swagger';

@Controller('boards')
@ApiTags('Board API')
@UseGuards(AuthGuard())
export class BoardsController {
  private logger = new Logger('BoardsController');
  constructor(private boardsService: BoardsService) {}

  @Post()
  @ApiOperation({
    summary: 'Board 생성 API',
    description: '게시글을 생성한다.',
  })
  @ApiCreatedResponse({
    description: '게시글을 생성한다.',
    type: Board,
  })
  @UsePipes(ValidationPipe)
  createBoard(
    @Body() createBoardDto: CreateBoardDto,
    @GetUser() user: User,
  ): Promise<Board> {
    this.logger.verbose(`User ${user.username} creating a new board.
    Payload: ${JSON.stringify(createBoardDto)}`);
    return this.boardsService.createBoard(createBoardDto, user);
  }

  @Patch('/:id/status')
  @ApiOperation({
    summary: 'Status 변경 API',
    description: '게시글의 status를 변경한다.',
  })
  @ApiCreatedResponse({ description: 'status를 변경한다.', type: Board })
  updateBoardStatus(
    @Param('id', ParseIntPipe) id,
    @Body('status', BoardStatusValidationPipe) status: BoardStatus,
  ): Promise<Board> {
    return this.boardsService.updateBoardStatus(id, status);
  }
  // ...
 }

 

• 경로 옆에 API 제목들이 추가되었다.

• 그럼에도 아직 안에 내용들은 추가되지 않았다.
• 이는 Entity 파일과, DTO 파일에서의 수정이 필요하다.

 

 

5. Entity 파일에 추가

import { ApiProperty } from '@nestjs/swagger';

@Entity()
export class Board extends BaseEntity {
  @PrimaryGeneratedColumn()
  @ApiProperty({ description: 'id' })
  id: number;

  @Column()
  @ApiProperty({ description: '제목' })
  title: string;

  @Column()
  @ApiProperty({ description: '내용' })
  description: string;

• ApiProperty 데코레이터로 설명들을 추가한다.

• 위처럼 Response 부분에 Example Value와 Schema는 각 엔티티에 대한 설명이 추가된다.

 

 

6. DTO 파일에 추가

import { ApiProperty } from '@nestjs/swagger';

export class CreateBoardDto {
  @ApiProperty({ description: '게시글 제목' })
  @IsNotEmpty()
  title: string;

  @ApiProperty({ description: '게시글 내용' })
  @IsNotEmpty()
  description: string;
}

• dto 파일에도 ApiProperty 데코레이터로 설명들을 추가한다.

• Request 부분의 Example Value와 Schema에 설명들이 추가된다.

 

---

전체 Swagger 적용결과