Swagger JSON 파일을 html로 변환 하기

Nestjs와 swagger를 함께 사용하고 있는 상황에서 swagger ui를 산출물로 제출해달라는 요청을 받았습니다. @redocly/cli 모듈을 이용하면 쉽게 html로 산출물을 생성 할 수 있습니다.

@redocly/cli 설치

다음 명령어로 쉽게 설치 할 수 있습니다.

$ npm install @redocly/cli -g

Nestjs 설정 확인

Nestjs의 swagger 설정이 아래와 같이 되어 있다고 가정합니다.

// main.ts

....
const config = new DocumentBuilder()
    .setTitle('Petaverse API SERVER')
    .setDescription('The Petaverse API description')
    .setVersion('1.0')
    .addBearerAuth()
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('docs', app, document); // docs 를 주소로 사용
....

api-server/docs-json 로 접근하면 swagger의 json 형식의 output을 확인 할 수 있습니다.

swagger HTML 결과문 생성 명령어

# 1. 주소 직접 접근
$ redocly build-docs https://api-server/docs-json -o swagger.html

# 2. 파일로 접근
$ $ redocly build-docs test.json -o swagger.html

-o 는 OUTPUT 옵션으로 저장될 파일 명을 설정 합니다

build-docs 옵션 외에도 lint 옵션으로 swagger 설정이 잘 되었는지 확인도 가능합니다 .

참고자료

• Converting Swagger specification JSON to HTML documentation
• @redocly/cli