[Scalar] nestjs API 문서 작성 하기 (feat swagger)

들어가며

프로젝트 개발을 하다보면 백앤드와 프론트 앤드의 커뮤니테이션이 가장 중요합니다

이 때 백엔드에서 만든 API에 필요한 데이터 들을 말로 전달하기엔 너무 힘들고 귀찮은 과정이기 때문에 API 문서를 작성해서 프론트 앤드에게 정보를 건내주면 훨신 좋을 것 같은데요

 

이때  백앤드 개발자들이 많이 사용하는 swagger 라이브러리가 있는데요 swagger도 좋은 문서 라이브러리지만 가독성이 조금 떨어진다는 단점이 있습니다 UI 가 개인적으로 좀 구린 것 같아요 ㅋㅋ..

 

swagger 라이브러리

 

그래서 요즘 뜨고 있는 문서 라이브러리를 소개해드릴려고 합니다. 

 

Scalar

https://scalar.com/

Scalar — Document, Discover and Test APIs

Scalar 로 구축한 API 문서입니다.

 

좌측을 메뉴로 구성했고 본문에 API 문서들이 있는 모습입니다 swagger 보다 UX/UI 적으로 깔금해서 보기 좋네요!!

 

 

이제 코드에 적용 해 보겠습니다

 

저는 nestjs로 백엔드를 구성했습니다!

 

$ npm install @scalar/nestjs-api-reference

 

npm 으로 패키지를 설치 할 수 있습니다

 

Scalar 는 nestjs/swagger 의 문법을 그대로 따르기 때문에 swagger 에서 Scalar 로 마이그레이션 하기가 쉽습니다

 

controller 부분을 보겠습니다

 

@Controller('question')
export class QuestionController {
  constructor(private readonly questionService: QuestionService) {}

  @ApiTags('질문')
  @ApiOperation({ summary: 'Get list question' })
  @Get('list')
  @HttpCode(HttpStatus.OK)
  @ResponseList(GetQeustionDto)
  @ResponseError([ErrorCode.NOT_FOUND_CONTENT])
  async getList(): Promise<ResponseListDto<GetQeustionDto>> {
    const result = await this.questionService.getList();

    return new ResponseListDto<GetQeustionDto>(
      result.map((dto) =>
        GetQeustionDto.from({
          id: dto.id,
          content: dto.content,
          sort: dto.sort,
          type: dto.type,
          questionSub: dto.questionSub.map((sub) => ({
            id: sub.id,
            questionId: sub.questionId,
            type: sub.type,
            content: sub.content,
          })),
        }),
      ),
    );
  }
}

 

간단하게 개발한 question controller 입니다

 

getList()메서드 위 쪽에 Swagger 데코레이션을 통해서 적용을 해놨습니다. @ApiTags 라던가 @ApiOperation 등 기존에 사용하던 데코레이션을 Scalar 에 사용할 수 있습니다.

 

설정 코드는 swagger를 설정한 코드에서 진행 하면 됩니다.

 

import { INestApplication } from '@nestjs/common';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { apiReference } from '@scalar/nestjs-api-reference';
import { ConfigService } from 'src/config/config.service';

export function setupSwagger(app: INestApplication) {
  const config = new DocumentBuilder()
    .setTitle('Maestro Api Document')
    .setDescription('Maestro Api Document')
    .setVersion(ConfigService.getConfig().API_VERSION)
    .build();

  const document = SwaggerModule.createDocument(app, config);

  app.use(
    '/docs',
    apiReference({
      spec: {
        content: document,
      },
    }),
  );
}

 

DocumentBuilder로 설명 및 추가 데이터를 작성해주고 app 객체를 통해 설정을 해줍니다.

 

사실상 swagger로 문서 개발을 해주고 apiReference 를 사용해 간단하게 설정 하면 됩니다!

 

 

프로젝트를 개발할땐 문서가 많이 중요한데 대중적인 swagger 도 좋지만 가독성 좋은 UX/UI를 통해 문서화 한다면 좀 더 좋은 퍼포먼스가 나오지 않을까 기대하고 있습니다!