Skip to content

Swagger 사용법

Jump to bottom
Time Gambit edited this page Mar 23, 2023 · 3 revisions

Swagger 문서 보는 법

/api에 접속하면 볼 수 있습니다.

DTO & Entity 관련

export class CreateUserQueryDto {
  @ApiProperty({
    description: '트랜잭션 성공 여부',
    type: String, // 명시해주었으므로 Swagger 문서에 success는 boolean이 아닌 string으로 표기, 만약 명시해주지 않았다면 boolean으로 표기됨
  })
  @IsBoolean()
  @Transform(({ value }) => value === 'true')
  success: boolean;

@ApiProperty({
    required: true, // 명시해주었으므로 Swagger 문서에 required로 표기됨(@ApiPropertyOptional이 무시됨), 만약 명시해주지 않았다면 required가 아닌 것으로 표기됨
  })
  @ApiPropertyOptional() // 위에서 required: true로 명시해주지 않았다면, @ApiPropertyOptional()의 존재여부에 따라 required 여부가 결정
  @IsPositive()
  @Transform(({ value }) => Number(value))
  time?: number;
}

  • @ApiProperty

    SchemaObject 에 여러 속성들이 있다. 아래는 그 중에서도 자주 쓸만한 것들을 나열한 것.

    • type: 타입을 지정해줄 수 있음
    • isArray: 배열형태인지 지정
    • minimum: 값의 최솟값 지정
    • maximum: 값의 최댓값 지정
    • exclusiveMinimum/exclusiveMaximum: 최소/최대값을 검사에 포함할지 여부
    • minLength: 문자열의 최소 길이 지정
    • maxLength: 문자열의 최대 길이 지정
    • pattern: 허용하는 문자열을 정규식으로 표현
    • default: 기본값을 지정 (단, example이 지정되었을 경우 무시됨)
    • required: 반드시 있어야하는지 여부 (@ApiPropertyOptional을 이용할 수도 있음)
    • example: 예시를 보여줄 수 있음
    • description: 해당 필드에 대한 설명 추가

  • @ApiPropertyOptional

    기본적으로 @ApiProperty() 와 동일하나 required: false 가 기본적으로 지정되어 있음

EndPoint 관련

import {
  Controller,
  Get,
  Post,
  Query,
} from '@nestjs/common';
import {
  ApiBadRequestResponse,
  ApiInternalServerErrorResponse,
  ApiOkResponse,
  ApiOperation,
  ApiTags,
} from '@nestjs/swagger';

import { UserService } from '@/api/user/user.service';
import {
  CreateUserQueryDto,
  CreateUserRetDto,
} from '@/dto/user/create-user.dto';
import { User } from '@/entity/user.entity';

@ApiTags('user')
@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @ApiInternalServerErrorResponse({
    description: '데이터 베이스에서 제대로 값을 읽어오지 못한 경우',
  })
  @ApiOkResponse({
    type: User,
    isArray: true,
  })
  @ApiOperation({
    summary: '모든 유저정보 데이터 가져오기',
    description: '설명',
  })
  @Get()
  async getUsers() {
    return this.userService.getUsers();
  }

  @ApiInternalServerErrorResponse({
    description: '트랜잭션 실패한 경우',
  })
  @ApiBadRequestResponse({
    description: '올바른 쿼리를 넣어주지 않은 경우',
  })
  @ApiOkResponse({
    type: CreateUserRetDto,
    isArray: true,
  })
  @ApiOperation({ summary: '3 * time 만큼의 새로운 유저 생성' })
  @Post(':id?')
  async createUser(@Query() { time, success }: CreateUserQueryDto) {
    return time
      ? this.userService.createUserWithTime(time, success)
      : this.userService.createUser(success);
  }
}

  • @ApiTags

    api들을 하나의 태그로 묶어줄 수 있다. Controller 클래스에 적어주면 해당 Controller의 모든 함수에 적용됨

    image

  • @ApiOperation

    api에 대한 설명을 추가할 수 있다.

    • summary: 요약. (펼치기 전에 보이는 부분. 위 사진에서는 ‘모든 유저정보 데이터 가져오기’ 부분)
    • description: 설명. (펼친 후에 보여지는 부분) 요약보다 자세한 설명을 작성할 수 있다.

  • @ApiResponse

    api 응답에 대한 설명을 추가할 수 있다.

    • 옵션
      • status: 상태코드
      • type: 응답 데이터 타입
      • isArray: 응답 데이터의 배열 여부
    • status를 지정하는 대신 각 상태코드에 해당하는 ApiResponse를 사용할 수 있다.
      • @ApiOkResponse: 200
      • @ApiNotFoundResonse: 404
      • @ApiInternalServerErrorResponse: 500

  • @ApiQuery & @ApiParam

    api 요청과 함께 받는 데이터인 쿼리와 파라미터에 대해 명시적으로 지정해주는 기능. 함수의 인자에 @Query() 와 @Param 을 사용해도 자동적으로 생성되므로 굳이 사용할 필요 없다고 사료됨.

Clone this wiki locally