TypeScript + Swagger 개발 환경 자동화: 디버깅용 Swagger 자동 실행

기존 c# ASP.NET Core를 사용하다가 Nest.js를 사용하고 있는데 제가 개인적으로 가장 불편하게 생각하는게 하나가 있습니다.

그건 바로..

닷넷 코어 비주얼 스튜디오에서는 디버깅을 시작하면 바로 스웨거 브라우저가 실행되고 디버깅이 끝나면 해당 브라우져가 같이 꺼집니다. 

하지만 Nest.js에서 아래와 같이 스웨거를 사용할때 주소 창에 일일히 api-docs 같은 경로를 입력해야만 스웨거에 접속하는 경험을 하실겁니다.

주소창에 입력해야함.

저는 원래 닷넷코어의 비주얼스튜디오에서 스웨거를 자동으로 띄워주는 환경에 익숙해져서 그런진 몰라도 저렇게 일일히 치는게 상당히 귀찮습니다..

그래서 Nest.js로도 닷넷코어의 스웨거 자동 띄우기를 구현하고자합니다.
방법은 아주간단합니다.

반응형

1.launch.json 설정

launch.json을 열어서 아래와 같은 구성을 추가해 줍니다.

    {

      /*스웨거 자동 생성성*/

      "type": "pwa-node",

      "request": "launch",

      "name": "Nest Debug",

      "runtimeExecutable": "npm",

      "runtimeArgs": ["run", "start:debug"],

      "env": {

        "NODE_ENV": "development",

        "ENABLE_SWAGGER": "true"

      },

      "serverReadyAction": {

        "action": "openExternally",

        "pattern": "Swagger 문서: http://localhost:3000/api-docs",

        "uriFormat": "http://localhost:3000/api-docs"

      }

    }

이 설정의 의미는 각각 아래와 같습니다.

• request:"launch" : 디버거가 프로세스를 실행해 붙도록 지시
• name:"Nest Debug" : 디버거 구분을 위한 이름 ide에서 ctrl+Shift+p 후 디버그 패널에서 해당 이름의 디버그를 찾아서 실행하면 됩니다.
• runtimeExecutable:"npm" : 디버거가 어떤 실행 파일을 통해 서버를 띄울지 지정합니다. 여기서는 npm을 사용해 스크립트 실행합니다.
• runtimeArg : ["run","start:debug] : npm에게 전달할 인수입니다. 해당 명령어로 실행해 Nest.js 서버를 디버그 모드로 실행합니다.
• env: { "NODE_ENV": "development", "ENABLE_SWAGGER": "true" } : 디버깅 세션에서 활용될 환경변수를 지정합니다.
  NODE_ENV=development → 애플리케이션이 개발 모드로 동작하고, 개발 전용 설정(예: Swagger, verbose logging 등)에 활용할 수 있습니다.
  ENABLE_SWAGGER=true → main.ts에서 이 플래그를 확인해 Swagger UI를 활성화하도록 했을 때 사용됩니다.
• serverReadyAction
  서버가 특정 메세지를 출력하면 자동으로 브라우저를 띄우는 옵션입니다.
• action : "openExternally": 외부 브라우저를 실행합니다.
• pattern :스웨거 문서 경로 "http://localhost:3000/api-docs" 해당 문자열이 출력되는것을 감지합니다.
• uriFormat : 위 pattern이 감지되면 해당 uri주소를 열어줍니다.

2.Main.ts 

  const enableSwagger =

    process.env.ENABLE_SWAGGER === 'true' ||

    process.env.NODE_ENV !== 'production';

  if (enableSwagger) {

    const config = new DocumentBuilder()

      .setTitle('테스트 API')

      .setVersion('1.0')

      .addBearerAuth(/* ... */)

      .build();

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

    SwaggerModule.setup('api-docs', app, document, {

      swaggerOptions: { persistAuthorization: true },

    });

  }

위와 같이 스웨거 사용모드일때만 스웨거가 표시되게 해주고 상용 프로덕트일때는 제외 하도록 설정해줍니다.

  console.log('Swagger 문서: http://localhost:3000/api-docs');

 

그리고 밑에 부분에 console.log로 아까 launch.json에서 등록한 pattern까지 지정해주도록 합니다.

3.실행

1.crtl + shift + p로 select and Start Debugging에서 디버거를 선택해줍니다.

디버거 선택

Nest Debug 선택

2.디버깅 실행 

디버깅 실행후 pattern 확인

디버깅 중에 console.log의 패턴에서 스웨거가 뜨는지 확인해보면됩니다.

3.스웨거 문서 뜨는것 확인

console.log에서 실행되는 패턴을 감지하여 스웨거 문서가 자동적으로 뜨는것을 확인 할 수 있습니다.

이것으로 간단하게 디버깅시에 스웨거 문서가 자동적으로 띄워지도록 세팅을 해봤습니다.

물론 주소창에 치는게 더 좋으신 분도 있겠지만 저는 자동으로 스웨거가 뜨는게 편해서 이렇게 설정하여 사용하고 있습니다.

편하게 스웨거 띄우고 싶으신 분들은 이렇게 launch.json 설정을 변경하여 사용해보시기 바라겠습니다.