Swagger로 API 문서화

프론트엔드와 협업할 때 "어떤 API가 있고, 무엇을 보내면 무엇이 오는지"를 문서로 공유해야 한다. Swagger(OpenAPI)는 코드에 붙인 데코레이터로 이 문서를 자동 생성하고, 브라우저에서 바로 요청을 테스트할 수 있는 UI까지 제공한다.

설치는 npm i @nestjs/swagger다. DocumentBuilder, @ApiProperty 같은 아래 API는 초기 버전부터 거의 그대로다.

설정

// main.ts
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 
const config = new DocumentBuilder()
  .setTitle('NestJS Cats API')
  .setDescription('The cats API description')
  .setVersion('1.0.0')
  .addBearerAuth() // JWT 인증이 필요한 API를 문서에서 테스트할 수 있게
  .build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('docs', app, document); // http://localhost:8000/docs

엔드포인트 설명

@ApiTags('cats')
@Controller('cats')
export class CatsController {
  @ApiOperation({ summary: '고양이 회원가입' })
  @ApiResponse({ status: 201, description: '성공', type: ReadOnlyCatDto })
  @ApiResponse({ status: 500, description: '서버 에러' })
  @Post()
  async signUp(@Body() body: CatRequestDto) {
    return this.catsService.signUp(body);
  }
}

응답 DTO(type)는 그 DTO가 실제로 반환되는 상태 코드(보통 성공 응답 200/201)에 붙인다. 에러 응답에 붙이면 문서의 스키마가 실제 응답과 어긋난다.

요청·응답 스키마

DTO 필드에 @ApiProperty를 붙이면 문서에 예시와 설명이 표시된다.

export class ReadOnlyCatDto extends PickType(Cat, ['email', 'name'] as const) {
  @ApiProperty({ example: '64f1c2...', description: 'id', required: true })
  id: string;
}

// cats.schema.ts: 스키마 필드에 붙여 두면 PickType으로 만든 DTO가 그대로 상속
@ApiProperty({ example: 'cat@example.com', description: 'email', required: true })
@Prop({ required: true, unique: true })
@IsEmail()
email: string;

PickType·OmitType을 @nestjs/swagger에서 import해야 @ApiProperty 메타데이터도 함께 상속된다. (DTO와 Validation)

참고: nest-cli.json에 "plugins": ["@nestjs/swagger"]를 추가하면 CLI 플러그인이 DTO 속성을 읽어 @ApiProperty를 상당 부분 자동으로 붙여 준다.

문서 접근 보호

API 문서가 공개되어 있으면 공격자에게 지도를 건네는 셈이다. express-basic-auth로 문서 경로에 Basic 인증을 건다.

npm i express-basic-auth

import expressBasicAuth from 'express-basic-auth';
 
app.use(
  ['/docs', '/docs-json'],
  expressBasicAuth({
    challenge: true,
    users: { [process.env.SWAGGER_USER]: process.env.SWAGGER_PASSWORD },
  }),
);

계정 정보는 환경 변수로 관리한다.

express-basic-auth는 Express 전용 미들웨어다. Fastify 어댑터를 쓰면 다른 방식으로 바꿔야 한다.

핵심 정리

DocumentBuilder + SwaggerModule.setup('docs', ...)으로 문서 UI를 띄운다.
@ApiOperation, @ApiResponse, @ApiProperty로 설명·스키마를 채운다.
운영 환경의 문서 경로는 인증으로 보호한다.

참고: NestJS OpenAPI 문서

버그 제보

Swagger로 API 문서화

설정

엔드포인트 설명

요청·응답 스키마

문서 접근 보호

핵심 정리

댓글