[NestJS] Swagger 적용( 과 Swagger -> Redoc으로 변경..은 하려고하였으나~~ )

NestJS 애플리케이션에서 ReDoc을 사용하려면

NestJS용 Swagger(OpenAPI) 사양과의 통합을 제공하는 @nestjs/swagger 패키지를 설치해야 함

 

npm install @nestjs/swagger

 

NestJS 애플리케이션에서 swagger.options.ts 파일을 만들고 

OpenAPI 사양을 정의

여기에는 API 끝점, 요청 및 응답 본문 및 기타 관련 세부 정보에 대한 정보가 포함되어야 함

 

main.ts 파일 내에서 설정을 잡아줘야 함

이 파일에서 @nestjs/swagger에서 SwaggerModule을 가져오고 이를 사용하여 애플리케이션에서 Swagger를 활성화

 

import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const options = new DocumentBuilder()
  .setTitle('Title')
  .setDescription('Description')
  .setVersion('1.0') 
  .addTag('Tag')
  .build();

  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

 

npm run start를 사용하여 NestJS 애플리케이션을 실행

 

이렇게 하면 서버가 시작되고 /api 엔드포인트에서 ReDoc 문서를 사용할 수 있다.

 

ReDoc 문서의 모양을 사용자 지정하려면 createDocument 메서드에 추가 옵션을 전달할 수 있다.

 

예를 들어 addBearerAuth 메서드를 사용하여 API 호출에 인증 헤더를 추가하거나 

setBasePath 메서드를 사용하여 API 엔드포인트의 기본 경로를 지정할 수 있다.

 

@nestjs/swagger 설명서에서 이러한 옵션에 대한 자세한 정보를 찾을 수 있다.

Swagger은 엄청 쉽게 구현이 되는구나.

 

 

---

아래는 Redoc으로 변경하기위한 여정입니다.

결론 : Nest 8버전으로 구현해야할것같다.

 

 

 

여기서 Swagger가 아닌 Redoc을 사용하려면

nestjs-redoc 패키지가필요하다

 yarn add nestjs-redoc

*왜 Yarn으로 했는가?

npm으로 설치 시 

ERESOLVE unable to resolve dependency tree

관련 에러가 났었다.

그래서 찾아보던 중 Yarn으로 만든 레포면 Yarn으로 설치하면 이 문제가 해결된다고해서 했더니.

잘 설치 됨.

 

 

그리고 코드를 작성한다

  const document = SwaggerModule.createDocument(app, options);
  // SwaggerModule.setup('api', app, document);

  const redocOptions: RedocOptions = {
    title: 'Hello Nest',
    logo: {
      url: 'https://redocly.github.io/redoc/petstore-logo.png',
      backgroundColor: '#F0F0F0',
      altText: 'PetStore logo'
    },
    sortPropsAlphabetically: true,
    hideDownloadButton: false,
    hideHostname: false,
    auth: {
      enabled: true,
      user: 'admin',
      password: '123'
    },
    tagGroups: [
      {
        name: 'Core resources',
        tags: ['cats'],
      },
    ],
  };

  await RedocModule.setup('/api', app, document, redocOptions);

 

 

오류가 발생했다.

마지막 구문인 RedocModule.setup 중, app 파라미터에서 오류가 잡힌다.

Type 'INestApplication' is missing the following properties from type 'INestApplication': listenAsync, 

startAllMicroservicesAsync

await RedocModule.setup('/api', app, document, redocOptions);

 

오류 메시지는 INestApplication 인터페이스에 RedocModule.setup 메서드에 필요한

listenAsync 및 startAllMicroservicesAsync 속성이 없음을 나타냄

 

원인

- 오래된 @nestjs/redoc 패키지

@nestjs/redoc 패키지의 최신 버전을 사용하고 있는지 확인이 필요

필수 속성이 없는 이전 버전을 사용하는 경우 이 오류가 발생할 수 있음.

 

- INestApplication 인터페이스를 올바르게 가져오지 않음

@nestjs/common 패키지에서 INestApplication 인터페이스를 가져오고 있는지 확인이 필요

다른 위치에서 가져오는 경우 필요한 속성이 없을 수 있다.

 

맞다 그냥 버전문제인것같다.

앞서 났던 오류를 그냥 yarn으로 처리했던 부분 기억나는가?

npm으로 설치할 때면 아래와같은 오류를 확인할 수 있었다.

peer @nestjs/core@"^8.0.0" from nestjs-redoc@2.2.2

즉, nest-redoc2.2.2를 설치하려면 nestjs/core가 8.0.0버전이여야 한다는 것.

그걸 yarn으로 해결해서 설치는되었지만, 

2.2.2가 core8.0.0에 의존적이였던 부분에서 문제가 터져버린 것 아닐까 싶었다.

이 부분이 peerDependencies라고 한다.

명시한 의존버전에 안맞을 경우 오류를 발생.

 

그러니까 nestjs/core의 버전을 낮추거나 .. 다른 방법을 찾아야할 것 같은데..

 

다른방법

npm3~6버전에서는 peerDependencies가 에러 발생시키지않고 경고만 보여줬는데

npm7버전 이후에서는 peerDependencies가 에러를 발생시키는 것

현재 npm버전은 8.19

이를 해결하기위해서는

 

npm install -legacy-peer-deps로 설치하면된다.

npm3~6처럼 경고만 하게끔 하는 옵션이다.

 

yarn으로 설치했던걸 삭제해주고

npm i --legacy-peer-deps nestjs-redoc 

로 재설치해줬다.

 

근데문제는 똑같다..

 

8로 마이그레이션 해줘야하나싶다.

머리가아프다.

 

 

LINK

nestjs-redoc : https://github.com/mxarc/nestjs-redoc

nestjs/swagger : https://docs.nestjs.com/openapi/introduction

GitHub - mxarc/nestjs-redoc: 📘 ReDoc frontend for you NestJS swagger API documentation