NestJS 스웨거(Swagger) 설정

스웨거란, API를 자동으로 문서화 해주는 기능입니다.

해당 문서를 통하여 사용자는 API 인터페이스 규격과 설명을 확인할 수 있고, 입력값을 직접 설정하여 API를 호출하여 테스트도 가능하다는 장점이 있습니다.

 

테크팀은 스프링 프로젝트들에 대하여 스웨거를 설정하여 API 문서를 회사 내부 개발자 및 외부 협력업체 개발자 분들에게 제공하고 있기 때문에 문서 통일화를 위하여 NestJS 프로젝트 또한 스웨거 설정이 필요하였습니다.

 

"dependencies": {
    "@nestjs/swagger": "^7.1.16",
},

package.json에 다음을 추가하고 패키지를 설치하자.

 

const swaggerUiPath = contextPath + configService.get<string>('springdoc.swagger-ui-path');

const apiDocsPath = contextPath + configService.get<string>('springdoc.api-docs-path');

const swaggerConfig = new DocumentBuilder()
      .setTitle('App API')
      .setDescription('"App REST API 설명서입니다.')
      .setVersion('v1')
      .setContact('플래티어', 'https://www.plateer.com/company/plateer', '')
      .addApiKey(
        {
          type: 'apiKey',
          name: 'api-auth-key',
          in: 'header',
        },
        'api-auth-key',
      )
      .build();
    
const swaggerDocument = SwaggerModule.createDocument(app, swaggerConfig);
SwaggerModule.setup(swaggerUiPath, app, swaggerDocument, {
	jsonDocumentUrl: apiDocsPath,
    swaggerOptions: { defaultModelsExpandDepth: -1 },
});

다음과 같이 스웨거 옵션을 설정하고 스웨거 모듈을 생성하여 준다.

 

@Get('/swaggerTest')
@ApiOperation({
    summary: '스웨거 테스트',
    description:
      '' + '# 기능설명\n' + '## * 스웨거를 테스트하기 위한 API 입니다.',
})
@ApiQuery({
    name: 'searchWord',
    schema: {
      type: 'string',
    },
    description: '검색어',
    example: '상품명',
    required: false,
})
@ApiQuery({
    name: 'langCd',
    schema: {
      type: 'string',
    },
    description: '다국어 코드',
    example: 'ko',
})
@ApiResponse({
    status: 200,
    description: '' + '## 검색성공 결과\n' + '### * 상품목록 반환합니다.\n',
    content: {
      'application/json': {
        schema: {
          type: 'object',
          properties: {
            payload: {
              type: 'object',
              example: [
                {
                  searchDataList: [
                    {
                      test1: 'string',
                      test2: 'string',
                    },
                  ],
                  totalCount: 'number',
                },
              ],
            },
          },
        },
      },
    },
})
async swaggerTest(@Res({ passthrough: true }) res: Response) {
    res.status(HttpStatus.OK);
    return ['swaggerTest'];
}

컨트롤러 라우터에 API 설명에 대한 스웨거 설정을 합니다.

 

마지막으로 서버를 시작후 스웨거 페이지에 접속하면 설정된 문서내용을 확인할 수 있습니다.

 

이상 스웨거(Swagger)에 대한 글을 마치며, 다음글에서는 yaml 파일로 설정을 관리하는 방법에 대해 간단하게 설명하도록 하겠습니다.