[NestJS] Nestia swagger 초기 설정에서 발생하는 문제

지금 NestJS 커뮤니티에 들어와 있는데 samchon 님이 개발하신(?) Nestia 라이브러리를 다들 많이 사용하시는 것 같아서 나도 프로젝트 하면서 부담가지지 않으면서 생각날때마다 조금씩 해보려고 한다.

 

개인적으로 문서를 보는 능력이 많이 부족하다고 생각되어서 문서를 보면서 직접 공부겸 프로젝트를 해보는 경험도 해보려고 한다.

 

Nestia란?

Nestia는 NestJS를 위한 helper library 라고 할 수 있다. Nestia를 사용하게 되면 다음과 같은 도움을 받을 수 있다고 한다.

 

- class-validator에서 런타임 유효성 검사기는 기존보다 20,000배 빠르다.

- class-transformer에서 JSON Serialization은 기존보다 200배 빠르다.

- Swagger 생성 유연함 및 자동 E2E 테스트 기능 생성기

- 클라이언트를 위한 SDK를 생성함으로서 개발에 도움을 줄 수 있다.

 

나중에 어느정도 숙련이 되면 Nestia 초기 세팅할 때는 어떤 명령어를 작성해야 하고, 각 Nestia 라이브러리에는 어떤 것들이 있는지를 좀 더 세세하게 분석해보려고 한다.

 

문제점은?

우리는 root에 nestia.config.ts 파일을 만들고 npx nestia init 명령어를 통해 초기 세팅을 해줄 수 있다.

 

import { INestiaConfig } from '@nestia/sdk';

export const NESTIA_CONFIG: INestiaConfig = {
  /**
   * Accessor of controller classes.
   *
   * You can specify it within two ways.
   *
   *   - Asynchronous function returning `INestApplication` instance
   *   - Specify the path or directory of controller class files
   */
  input: ['src/controllers'],

  /**
   * Building `swagger.json` is also possible.
   *
   * If not specified, you can't build the `swagger.json`.
   */
  swagger: {
    /**
     * Output path of the `swagger.json`.
     *
     * If you've configured only directory, the file name would be the `swagger.json`.
     * Otherwise you've configured the full path with file name and extension, the
     * `swagger.json` file would be renamed to it.
     */
    output: 'dist/swagger.json',
  },

  /**
   * Output directory that SDK would be placed in.
   *
   * If not configured, you can't build the SDK library.
   */
  output: 'src/api',

  /**
   * Target directory that SDK distribution files would be placed in.
   *
   * If you configure this property and runs `npx nestia sdk` command,
   * distribution environments for the SDK library would be generated.
   *
   * After the SDK library generation, move to the `distribute` directory,
   * and runs `npm publish` command, then you can share SDK library with
   * other client (frontend) developers.
   */
  // distribute: "packages/api",

  /**
   * Whether to use propagation mode or not.
   *
   * If being configured, interaction functions of the SDK library would
   * perform the propagation mode. The propagation mode means that never
   * throwing exception even when status code is not 200 (or 201), but just
   * returning the {@link IPropagation} typed instance, which can specify its body
   * type through discriminated union determined by status code.
   *
   * @default false
   */
  // propagate: true,

  /**
   * Allow simulation mode.
   *
   * If you configure this property to be `true`, the SDK library would be contain
   * simulation mode. In the simulation mode, the SDK library would not communicate
   * with the real backend server, but just returns random mock-up data
   * with requestion data validation.
   *
   * For reference, random mock-up data would be generated by `typia.random<T>()`
   * function.
   *
   * @default false
   */
  // simulate: true,
};

export default NESTIA_CONFIG;

 

그러면 다음과 같이 코드가 작성되어 있을 것이다. 여기서 swagger 쪽을 보면 swagger.json이 생성될 위치를 언급해주는 것인데 필자는 dist 파일의 root에 생성되게끔 설정해주었다. 

 

여기서 문제는 생성은 잘되지만 npm run start:dev 명령어를 통해 서버를 구동시키고 나면 dist에 swagger.json이 없어진다는 것이다.

물론 새로 디렉토리를 생성해서 그쪽으로 경로 설정을 해주면 되긴하지만 왜 안되는지 궁금해서 알아보기로 했다.

 

결론

dist는 기본적으로 빌드하면 삭제옵션이 있다고 한다. nest-cli.json 파일을 확인해보면 compilerOptions - deleteOurDir이 true로 되어있을 것이다. 

 

그래서 간단하게 로직을 정리해보자면..

 

- 우리는 npx nestia swagger를 통해 swagger.json을 생성한다. 그러면 dist의 root에 swagger.json이 생성된 것을 확인할 수 있다.

- 만약 이후에 npm run start:dev를 통해 서버를 구동시킬 경우 deleteOurDir가 true이면 dist 파일이 삭제되었다가 새로 생성이 되기 때문에 swagger.json을 읽어오지 못하는 것이다.

- 따라서 deleteOurDir 옵션을 false로 설정해주면 읽어올 수 있다.

 

참고자료

- https://nestia.io/docs/

Nestia Guide Documents - Index

- https://docs.nestjs.com/cli/monorepo

Documentation | NestJS - A progressive Node.js framework