OpenAPI

OpenAPI는 RESTful API를 정의하고 설명하는 데 사용하는 언어에 구애 받지 않는 형식이라고 보면된다. 가장 많이 쓰는건 Swagger이며, 나도 스웨거를 기준으로 설명해볼것이다.

설치

#npm
npm i -s @nestjs/swagger
#yarn
yarn add @nestjs/swagger

설정

swagger.config.ts

export const swaggerConfig = new DocumentBuilder()
  .setTitle('Test Open API')
  .setDescription('테스트용 오픈API입니다.')
  .setVersion('1.0')
  .build();

가장 기본이되는 설정 형태이다.

나중에 Auth파트에서 Swagger에 OAuth, APIkey, Bearer등록 하는법도 배워 볼 것이다.

main.ts

import { swaggerConfig } from '@config/swagger.config';
import { NestFactory } from '@nestjs/core';
import { SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app/app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const swaggerDocument = SwaggerModule.createDocument(app, swaggerConfig);
  SwaggerModule.setup('api', app, swaggerDocument);
  await app.listen(8080, () => {
    console.log('Server running');
  });
}
bootstrap();

위 처럼 부트스트랩에 등록하고나면 끝이다. (너무 간단)

문법

가장 많이 쓰는 것만 알려주겠다.

@ApiProperty()

주로 컬럼단위에서 쓰인다.

import { baseEntityUUID } from '@config/base.entity.config';
import { BeforeInsert, Column, Entity } from 'typeorm';
import * as bcrypt from 'bcrypt';
import { ApiProperty } from '@nestjs/swagger';

@Entity('account')
export class Account extends baseEntityUUID {
  @ApiProperty({
    type: String,
    description: '유저 이름',
    nullable: false,
    example: 'Artlogy',
    minLength: 1,
    maxLength: 24,
  })
  @Column({ length: 24, comment: '유저 이름', nullable: false })
  name: string;

  @ApiProperty({
    type: String,
    description: '이메일',
    uniqueItems: true,
    nullable: false,
    example: 'artlogy@example.com',
  })
  @Column({ length: 128, comment: '이메일', unique: true, nullable: false })
  email: string;

  @ApiProperty({
    type: String,
    description: '패스워드',
    nullable: false,
    minLength: 8,
    maxLength: 48,
  })
  @Column({
    length: 48,
    comment: '패스워드',
    nullable: false,
  })
  password: string;

  @Column({ length: 128, comment: '리플래시 토큰', nullable: true })
  refresh_token: string;

  @BeforeInsert()
  async pwdHashing(pwd: string) {
    this.password = await bcrypt.hash(
      pwd || this.password,
      process.env.PASSWORD_SALT,
    );
  }
}

왜 Entity에 했음?

Dto에서는 PickType을 사용하여 중복코드를 최소화 하기 위함이다.
create-account.dto

import { PickType } from '@nestjs/swagger';
import { Account } from '../entities/account.entity';
export class CreateAccountDto extends PickType(Account, [
  'email',
  'name',
  'password',
] as const) {}

배열

@ApiProperty({ type: [String] })
names: string[];

Enum

enum UserRole {
  Admin = 'Admin',
  Moderator = 'Moderator',
  User = 'User',
}
...
 @ApiProperty({ enum: UserRole, name:"enum" })
 @Column({ type: 'enum', enum: UserRole, name: 'enum' })
 enumTest!: string;

@ApiTags()

주로 컨트롤러 단에서 쓰인다.

@ApiTags('account')
@Controller('account')
export class CatsController {}

default 태그 아래 있던 API들이 account로 tag이름이 바뀐 걸 볼 수있다.

@ApiOperation()

주로 endpoint, api단에서 쓰인다.

  @Post()
  @ApiOperation({
    summary: '회원 생성 API',
    description: '회원가입 기능을 담당하는 API입니다.',
  })
  create(@Body() createAccountDto: CreateAccountDto) {
    return this.accountService.create(createAccountDto);
  }

가장 많이 쓰는 건 여기까지다.
Header나 body params, 예외처리까지 스웨거에서 정의할 수 있지만
그건 따로 보거나 진행하다 나오면 언급하고 가겠다.