Serverless 마이크로서비스 환경에서 API Docs 통합하기

API Docs

NestJS를 사용하면, @nestjs/swagger 라는 라이브러리로 쉽게 API Docs를 구성할 수 있습니다.

라이브러리를 사용하면, 하나의 서비스에서 API Docs를 생성하는 건 매우 쉬운 일입니다.

아래 코드는 NestJs 공식 문서에 있는 @nestjs/swagger로 Swagger UI를 구성하는 코드입니다.

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

import {AppModule} from './app.module';

async function bootstrap() {
    const expressApp = express();

    const app = await NestFactory.create(AppModule, new ExpressAdapter(expressApp));

    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);

    await app.listen(3000);
}

bootstrap();

NestFactory에서 AppModule을 사용해 app을 만들고, 그 app과 swagger config를 사용해서 document를 만들고, 마지막으로 setup해주는 과정을 확인할 수 있습니다.

이처럼 하나의 프로젝트에서 API Docs를 생성하는건 매우 쉬운 일입니다.

그럼 서비스별로 프로젝트가 분리되어 있을 땐 API Docs를 어떻게 생성해야 할까요?

이 글에선, 위 코드를 기반으로 여러 서비스에 분리되어 있는 모듈들을 하나의 API Docs로 합치는 과정을 보여드리겠습니다.

예제는 Express 기반이지만, 꼭 Express 기반이 아니더라도 각각의 기반이 되는 프레임워크에 맞춰 조금씩만 수정하면 충분히 사용할 수 있을 것입니다.

1. Module 생성

여러 서비스에 분리되어있는 API Docs를 통합해주기 위해서 가장 먼저 해야 할 일은, document를 만들 app을 하나 새로 만들어 주는 것입니다.

그리고 app을 새로 만들기 위해선, 새로운 모듈이 필요합니다. 이 모듈이 분리된 여러 서비스의 모듈들을 import하는 하나의 큰 모듈이 될 것입니다.

A 서비스의 A Module과 B 서비스의 B Module을 하나의 docs로 합친다고 생각하면, 아래와 같은 모듈이 만들어 질 것입니다.

@Module({
    imports: [AModule, BModule]
})
export class DocsModule {}

이 모듈을 기반으로 bootstrap 함수에서 Swagger를 구성한다면, 아래와 같이 됩니다.

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

import {AppModule, DocsModule} from './app.module';

async function bootstrap() {
    const expressApp = express();

    const app = await NestFactory.create(AppModule); // 서버 실행을 위한 AppModule
    const docsApp = await NestFactory.create(DocsModule); // Docs 생성을 위한 DocsModule

    const config = new DocumentBuilder().setTitle('Cats example').setDescription('The cats API description').setVersion('1.0').addTag('cats').build();

    const document = SwaggerModule.createDocument(docsApp, config); // Docs 생성엔 docsApp 사용
    // SwaggerModule.setup('api', docsApp, document); // Docs 생성은 Api로 진행할 것이기 때문에, setup은 제거

    await app.listen(3000); // 서버 실행엔 app 사용
}

bootstrap();

2. SwaggerModule.setup 직접 구현

두 번째 과정을 설명하기 전에, SwaggerModule의 setup 함수가 어떻게 작동하는지부터 알아야 할 필요가 있었습니다.

SwaggerModule의 코드를 확인해보면,

...
class SwaggerModule {
    static createDocument(app, config, options = {}) {
        const swaggerScanner = new swagger_scanner_1.SwaggerScanner();
        const document = swaggerScanner.scanApplication(app, options);
        document.components = Object.assign(Object.assign({}, (config.components || {})), document.components);
        return Object.assign(Object.assign({ openapi: '3.0.0' }, config), document);
    }
    static setup(path, app, document, options) {
        const httpAdapter = app.getHttpAdapter();
        if (httpAdapter && httpAdapter.getType() === 'fastify') {
            return this.setupFastify(path, httpAdapter, document);
        }
        return this.setupExpress(path, app, document, options);
    }
    static setupExpress(path, app, document, options) {
        const httpAdapter = app.getHttpAdapter();
        const finalPath = validate_path_util_1.validatePath(path);
        const swaggerUi = load_package_util_1.loadPackage('swagger-ui-express', 'SwaggerModule', () => require('swagger-ui-express'));
        const swaggerHtml = swaggerUi.generateHTML(document, options);
        app.use(finalPath, swaggerUi.serveFiles(document, options));
        httpAdapter.get(finalPath, (req, res) => res.send(swaggerHtml));
        httpAdapter.get(finalPath + '-json', (req, res) => res.json(document));
    }
    static setupFastify(path, httpServer, document) {
        const hasParserGetterDefined = Object.getPrototypeOf(httpServer).hasOwnProperty('isParserRegistered');
        if (hasParserGetterDefined && !httpServer.isParserRegistered) {
            httpServer.registerParserMiddleware();
        }
        httpServer.register((httpServer) => __awaiter(this, void 0, void 0, function* () {
            httpServer.register(load_package_util_1.loadPackage('fastify-swagger', 'SwaggerModule', () => require('fastify-swagger')), {
                swagger: document,
                exposeRoute: true,
                routePrefix: path,
                mode: 'static',
                specification: {
                    document
                }
            });
        }));
    }
}
...

이런 클래스 하나가 나오게 되는데, 여기서 setup은 사실상 httpAdapter에 따라 다른 함수를 호출하는게 전부이므로, setupExpress, setupFastify가 API Docs를 구성해주는 함수라고 볼 수 있습니다.

httpAdapter가 없을 때 기본적으로 setupExpress를 호출하므로, Express를 기준으로 이야기 하겠습니다.

setupExpress가 하는 일은 크게 두 가지로 볼 수 있습니다.

1. 들어온 path에 swaggerUi.serveFiles 해주는 미들웨어 생성
2. 들어온 path에 get 요청을 보낼 시 swaggerUi.generateHTML의 결과값을 send해주는 API 생성

이 두 가지를 직접 구현해주면 API 호출시 Swagger UI를 볼 수 있을 것입니다.

우선, 미들웨어는 1번 과정에서 만든 bootstrap 함수에 추가해 주면 됩니다.

import {NestFactory} from '@nestjs/core';
import {SwaggerModule, DocumentBuilder} from '@nestjs/swagger';
import SwaggerUi from 'swagger-ui-express';

import {AppModule, DocsModule} from './app.module';

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

    const config = new DocumentBuilder().setTitle('Cats example').setDescription('The cats API description').setVersion('1.0').addTag('cats').build();

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

    app.use('/docs', SwaggerUi.serveFiles(docsApp)); // /docs 경로에 정적파일 제공 미들웨어 추가

    await app.listen(3000);
}

bootstrap();

그 다음 generateHTML은, 해당 미들웨어와 같은 경로의 API를 만들어서 리턴만 해주면 됩니다.

controller와 module은 생략하고 service의 코드만 보면 아래와 같이 간단히 해결 됩니다.

import SwaggerUi from 'swagger-ui-express';

@Injectable()
export class DocsService {
    getSwaggerHTML() {
        return SwaggerUi.generateHTML();
    }
}

이제 로컬에서 서버 실행 후 localhost:3000/docs로 접속하면 API Docs가 보일 것입니다.

3. Serverless Framework를 사용하는 경우, Api Event에 정적 파일 경로 추가

로컬에서 실행했을 때 문제가 없었으니, Serverless를 사용한 배포에서도 잘 나올거라 생각 했습니다.

하지만 배포 후 /docs 경로에 접근해보면 에러가 발생하며 API Docs가 보이지 않았습니다.

개발자 도구를 켜서 확인해보니, 정적 파일들을 get 하는 과정에서 문제가 있었습니다.

serverless.yml의 events 안의 정적 파일들 경로를 추가해줘야, 제대로 docs가 나오게 됩니다.

functions:
    Docs:
        handler: src/docs/lambda.handler
        events:
            - http:
                  path: /v2/docs
                  method: get
            - http:
                  path: /v2/docs/swagger-ui.css
                  method: get
            - http:
                  path: /v2/docs/swagger-ui-bundle.js
                  method: get
            - http:
                  path: /v2/docs/swagger-ui-standalone-preset.js
                  method: get
            - http:
                  path: /v2/docs/swagger-ui-init.js
                  method: get
            - http:
                  path: /v2/docs/favicon-32x32.png
                  method: get
            - http:
                  path: /v2/docs/favicon-16x16.png
                  method: get
            - http:
                  path: /v2/docs/favicon.ico
                  method: get

3 - 1. Webpack을 사용하는 경우, 정적파일 copy 및 미들웨어 경로 수정

Webpack을 사용한다면 swagger-ui.css is not found 에러가 발생하는 경우가 있을 것입니다.

이유를 알려면, serveFiles가 어떻게 작동하는지 알아야 합니다.

swagger-ui-express의 serveFiles를 확인해보면,

...

var swaggerUi = require('swagger-ui-dist')

...

var swaggerAssetMiddleware = options => {
    var opts = options || {};
    opts.index = false;
    return express.static(swaggerUi.getAbsoluteFSPath(), opts);
};

var serveFiles = function (swaggerDoc, opts) {
    opts = opts || {};
    var initOptions = {
        swaggerDoc: swaggerDoc || undefined,
        customOptions: opts.swaggerOptions || {},
        swaggerUrl: opts.swaggerUrl || {},
        swaggerUrls: opts.swaggerUrls || undefined
    };
    var swaggerInitWithOpts = swaggerInitFunction(swaggerDoc, initOptions);
    return [swaggerInitWithOpts, swaggerAssetMiddleware()];
};

...

정적파일을 가져오는 미들웨어가 하나 있고, 이 정적 파일들을 가져올 경로 및 정적 파일들이 swagger-ui-dist 라이브러리에 정의되어있습니다.

404 Not Found 가 발생하는 이유는, 정적 파일을 가져와야 할 경로에 해당 파일들이 없어서 나는 오류였고, 이를 해결하기 위해서 두 가지 과정이 필요했습니다.

1. webpack.config.js 파일에 CopyWebpackPlugin 사용
2. /docs 의 serveFiles 미들웨어 경로 수정

우선 1번 과정은, Webpack으로 빌드하는 과정에서 swagger-ui-dist의 정적 파일들이 빌드된 디렉토리에 존재하지 않았기 때문에 필요한 과정이었습니다.

...

plugins: [
        new CopyWebpackPlugin({
            patterns: [
                './node_modules/swagger-ui-dist/swagger-ui.css',
                './node_modules/swagger-ui-dist/swagger-ui-bundle.js',
                './node_modules/swagger-ui-dist/swagger-ui-standalone-preset.js',
                './node_modules/swagger-ui-dist/swagger-ui-init.js',
                './node_modules/swagger-ui-dist/favicon-32x32.png',
                './node_modules/swagger-ui-dist/favicon-16x16.png',
                './node_modules/swagger-ui-dist/favicon.ico',
                '.env'
            ]
        }),
        new webpack.IgnorePlugin(WebPackIgnorePlugin)
    ],

...

이런 식으로 webpack.config.js plugins에서 정적 파일들을 copy 해줘야 합니다.

2번 과정은, 저렇게 copy를 해도 기존 미들웨어의 경로대로 사용하면 카피된 파일들을 찾을 수 없기 때문에 필요합니다.

app.use('/v2/docs', express.static(path.join(__dirname, '..', '..')), SwaggerUi.serveFiles(document, customOptions));

express.static()으로 정적파일들을 가져 올 경로를 재설정 해줘야 제대로 정적 파일들이 import 가능합니다.

Dependabot

새로운 API가 추가될 때 마다 각 퍼블리시된 패키지들을 새로 설치하고, 배포해줘야 한다는 불편함이 있었습니다.

이 불편함 때문에 저희 개발팀이 생각해 낸 건, GitHub의 Dependabot이라는 기능입니다.

Dependabot은 설치되어있는 패키지, 라이브러리의 버전은 자동으로 체크하고, 업데이트가 있는 경우 Pull Request를 생성해 줍니다.

이를 이용해서 새로운 API가 추가될 때 마다 Dependabot이 이를 감지해서 Pull Request를 생성하고, 우리는 간단히 확인 후 Merge만 하면 되는 시스템을 만들었습니다.

Dependabot도 다른 GitHub Actions와 마찬가지로 .github 폴더 내에 Dependabot.yml 파일을 생성하여 GitHub에 푸시해두면, Dependabot이 작동하도록 되어있습니다.

version: 2

updates:
    - package-ecosystem: 'npm'
      directory: '/'
      schedule:
          interval: 'daily'
          time: '00:00'
      open-pull-requests-limit: 30
      allow:
          - dependency-name: '@package/*'
      ignore:
          - dependency-name: '@package/ignore_package'
          - dependency-name: '*'
            update-types: ['version-update:semver-patch']
      target-branch: 'master'

위 코드는 현재 Wonderwall API Docs에서 사용중인 Dependabot.yml 파일입니다.

중요한 부분만 설명을 하자면

1. schedule: Dependabot이 작동할 스케줄러를 만드는 부분입니다. interval daily는 매일 (주말 제외), time 00:00 은 UTC 기준 00시 00분에 돌아간다는 뜻입니다.

2. allow: Dependabot이 버전업을 감지할 패키지를 지정해주는 부분입니다. 기본적으로 모든 패키지에 대한 버전업을 감지합니다. @packege/*은 @package/ 로 시작하는 모든 패키지를 허용한다는 뜻입니다.

3. ignore: Dependabot이 버전업을 무시할 패키지를 지정합니다. @packege/*를 허용해 주고, 그 중 무시할 패키지를 지정해 줍니다.
   패키지를 ignore 할 수도 있고, update-types에서 버전이 오르는 패턴을 무시할 수도 있습니다. 현재 사용중인 version-update:semver-patch는 시멘틱 버저닝을 기준으로 patch 버전이 업데이트 되는 경우를 무시합니다.

4. target-branch: Pull Request를 생성해 줄 브랜치를 지정해줍니다.

이 외의 다른 옵션은 GitHub Docs의 Dependabot 에서 확인 할 수 있습니다.

Dependabot을 사용했을 때의 문제는, 버전업 된 패키지가 여러개일 때 Pull Request가 패키지의 개수대로 생성되는 것입니다.

그래서 여러개의 Pull Request를 하나로 합치는 작업이 추가되어야 했고 combine Dependabot prs workflow 를 찾았습니다.

Repository에 있는 yml파일을 .github 폴더에 넣고, README.md 파일에 적혀있는대로 따라가면 모든 Dependabot Pull Request를 합친 하나의 Pull Request를 만들어 줍니다.

마무리

원래는 API Docs를 합치며 했던 고민들 위주의 글을 적으려고 했는데, 적다보니 @nestjs/swagger 파헤치기 느낌의 글이 나오게 되었네요.

그렇게 어려운 내용은 아니지만, 라이브러리를 직접 확인하고 분석하느라 많은 삽질을 했던 작업이었습니다.

저와 같은 고민을 하고 계신 분께 도움이 되었으면 좋겠습니다.

긴 글 읽어주셔서 감사합니다.