스웨거

목차
1. 스웨거란?
2. 왜 사용을 할까?
3. 데코레이터
4. 사용법

1. 스웨거란?

• Rest API의 설계문서를 자동으로 생성하고 서버측 기능을 테스트할 수 있게 해주는 오픈 소스 API

2. 왜 사용을 할까?

개발을 할 때 가장 많이 하는 작업 중에 하나가 API 문서화다. 그 문서를 일일히 만들면 귀찮고 프론트 엔드와 백엔드 사이에서 소통하는 과정에서 문제가 발생하여 서로 맞지 않게 작업을 진행할 수도 있다. 스웨거는 몇 줄의 코드를 추가하여 자동으로 API문서를 만들어주고 프론트엔드 측 개발자가 백엔드의 기능이 정상적으로 테스트할 수 있게 해준다.

3. 데코레이터

1) ApiTags

▶ 특정 컨트롤러를 그룹화하는 것으로 UI에서 카테고리를 정리하는데 사용된다.

2) ApiOperation

▶ 각 엔드 포인트에 대한 설명을 제공한다.

@ApiOperation({ summary: '메서드 설명' })
@Get()
getData(){}

3) ApiResponse

▶ 응답의 상태 코드와 설명을 문서화한다.

@ApiResponse({ status: 200, description: 'Success' })
@ApiResponse({ status: 404, description: 'not found.' })
@Get()
getData(){}

4) ApiParam

▶ 요청시 URL에 포함되는 params를 문서화하는 것으로 Param데코레이터와 같이 사용하여 param변수 정보를 스웨거에 전달한다.

@ApiParam({ name: 'number', required: true, description: 'post number' })
@Get(':number')
getPostDetail({@Param("number")number:number){
}

5) ApiQuery

▶ 요청시 URL에 포함되는 쿼리스트링를 문서화하는 것으로 Query데코레이터와 같이 사용하여 쿼리스트링 정보를 스웨거에 전달한다.

@ApiQuery({ name: 'page', required: false, description: 'current page' })
@Get()
getPage(@Query('page') page: number) {

6) ApiBody

▶ 요청시 body에 포함되는 정보를 문서화하며 body에 어떤 데이터가 포함되는지 설명한다.

 

7) ApiBearerAuth

▶ 권한 인증에 사용되는 토큰에 대한 정보를 문서화하는데 사용된다.

@ApiBearerAuth()
@Get('profile')
getProfile(@Request() req) {
  return req.user;
}

 

8)ApiProperty

▶ DTO에 사용되며 클래스의 각 속성에 대한 정보를 문서화하는데 사용된다. 

export class CreateUserDto {
  @ApiProperty({ example: 'john_doe', description: 'The username of the user' })
  username: string;

  @ApiProperty({ example: 'password123', description: 'The password of the user' })
  password: string;
}

 

4. 사용법

1) 모듈설치

스웨거는 외부 모듈이기 때문에 npm에서 다운받아 사용을 해야한다.

npm install @nestjs/swagger

 

2) app설정

스웨거를 통해 문서를 생성하려면 몇가지 설정이 필요하다. 

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // swagger의 설정을 포함해서 문서를 생성
  // addTeg는 원하는 태그 추가
  const config = new DocumentBuilder().setTitle("제목").setDescription("설명").addTag("작성할 태그").build();
  // 문서의 형태로 생성
  const document = SwaggerModule.createDocument(app, config);
  // api 요청이 들어오면 document문서를 보여준다 
  SwaggerModule.setup("api", app, document);
  await app.listen(3000);
}
bootstrap();

 

 

설정을 통해 만들어진 페이지에 접속하면 다음과 같은 화면을 통해 추가했던 설명과 태그가 포함되어 API문서가 만들어진 것을 볼 수 있다. 

3) 데코레이터 사용

@Controller('test')
@ApiTags("test")
export class TestController {
  constructor(private readonly testService: TestService) { }
  @ApiOperation({ summary: 'test' })
  @ApiBody({
    schema: {
      type: 'object',
      properties: {
        name: { type: 'string', example: 'test' },

      }
    }
  })
  @Post()
  create(@Body() name: schema) {
    console.log(name);
  }
}

 

@ApiTags("test")

▶ 생성했던 태그와 매핑하는 부분

@ApiOperation({ summary: 'test' })

▶ 해당 메서드의 설명하는 부분

@ApiBody()

▶ 해당 메서드에 전달할 데이터에 대한 타입과 이름을 지정하는 부분

▶ 필요에 따라 ApiQuery나 ApiParam를 사용할 수도 있다.

 

 

4) 웹에서 확인해보기

웹에서 접속해보면 다음과 같은 화면이 뜬다. 해당 화면에서 서버의 메서드가 정상적으로 동작하는지 확인이 가능하다. 

try it out을 클릭하면 전달할 데이터를 수정하거나 요청을 진행할 수 있다. 원하는 데이터를 입력 후 excute버튼을 클릭하면 요청이 진행되며 실행 결과에 따라 응답코드를 반환해준다.

 

 

요청의 결과

스웨거에서 제공하는 화면에서도 결과를 확인할 수 있는데 정상적으로 실행이 됐을 경우 응답 코드를 반환해준다.

서버에서 body의 내용을 출력하는 코드를 작성하였는데 스웨거를 사용해서 요청했을 때 해당 메서드가 정상적으로 실행되는 것을 볼 수 있다.

 

 

참고자료

https://swagger.io/docs/specification/about/

About Swagger Specification | Documentation | Swagger