Swagger json 파일 활용하기

최근 @nest/swagger 라이브러리를 사용 하며 @Apiquery()로 받는 인자에 대해서는 schema를 작성해 주지 않는 문제가 있어 해결 했던 과정에 대해 써보자 한다.

// main.ts
  const config = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

nest.js 공식 문서에 나와있는 swagger적용 방식이다.

export declare class SwaggerModule {
    private static readonly metadataLoader;
    static createDocument(app: INestApplication, config: Omit<OpenAPIObject, 'paths'>, options?: SwaggerDocumentOptions): OpenAPIObject;
    static loadPluginMetadata(metadataFn: () => Promise<Record<string, any>>): Promise<void>;
    private static serveStatic;
    private static serveDocuments;
    static setup(path: string, app: INestApplication, documentOrFactory: OpenAPIObject | (() => OpenAPIObject), options?: SwaggerCustomOptions): void;
}
// swagger을 동작시켜 주는 SwaggerModule.setup을 보면 options라는 인자를 받는것이 보인다.

// setup함수의 인자인 path로 지정한 경로에 '-json'을 붙여서 접속 하면 swagger의 json파일을 볼 수 있다. ex) localhost:3000/path-json

이 json 파일을 가지고 https://editor.swagger.io 사이트에서 swagger-ui를 내가 원하는 대로 꾸밀수 있다.
사이트에 접속하여 components부분을 작성해 주고 json파일을 뽑아 낸다.

  const json: OpenAPIObject = JSON.parse(fs.readFileSync("./openapi.json", {encoding: 'utf8'}));
  
  SwaggerModule.setup('doc', app, json);

이 후 파일을 읽어 주고 json 형식으로 파싱을 해준 후 setup함수에 인자로 주면 내가 작성한 json파일 형식대로 swagger-ui가 나오는 것을 확인 할 수 있다.

2023-12-15

간단히 @ApiExtraModels(Class)
데코레이터를 달아주면 swagger-doc에 잘 추가 된다...