2017년 8월 30일 수요일

[AWS] Express에서 동작하는 Swagger UI server 만드는 방법(AWS API Gateway, Lambda 이용)

Express에서 동작하는 Swagger UI server 만드는 방법(AWS API Gateway, Lambda 이용)

[How to make Swagger UI server on Express (with AWS API Gateway and Lambda)]

AWS의 API Gateway와 Lambda를 이용하면 간편하게 REST API를 만들 수 있습니다.
(아래 링크에 제가 예전에 정리했던 REST API 포스팅이 있습니다. 하지만, 해당 방법으로는 GET, POST, PUT, DELETE 메서드를 모두 한번에 ANY 메서드로 처리하므로 Swagger로 표현할 수 없습니다. 그러니, 참고만 하시면 좋을 것 같습니다.
https://walkinpcm.blogspot.kr/2017/05/aws-aws-api-gateway-lambda-rest-api.html )
그런데, 만든 API에 대한 정보를 다른 사람에게 알려야할 때 API Gateway에 접속해서 보라고 하기에는 비효율적이고 한눈에 알아보기도 쉽지 않습니다.
즉, API Gateway로 만든 API도 문서화가 필요합니다. API문서화는 여러 방법이 있는데, 본 포스팅에서는 Swagger UI를 이용해서 API Document Web Page를 만들어보겠습니다.

0. 구조


Swagger UI는 다양한 서버에서 동작할 수 있는데, 여기서는 node 환경에서 express 웹서버로 Swagger UI를 구성하겠습니다.
그리고 해당 express 웹서버를 AWS Lambda에서 구동시키고, API Gateway를 이용해서 접속 URL을 획득해서 브라우저에서 접속할 수 있게 구성할 것입니다.
Swagger UI는 json 또는 yaml로 작성된 API 정의 문서를 보기 좋게 GUI로 보여주는데, 본 포스팅에서는 json 파일을 AWS S3에 업로드해서 이용합니다.

1. 필요한 것들

yarn과 Node js 설치는 일반적인 사항이므로 여기서는 다루지 않겠습니다.
또한, API Gateway + Lambda + Express 로 웹 어플리케이션을 Lambda에서 구동하는 방법은 아래 링크를 참고해주시기 바랍니다. 여기서는 코드만 바로 작성하도록 하겠습니다.
( 링크 : https://walkinpcm.blogspot.kr/2017/08/awsaws-lambda-express-react-application.html )

2. 프로젝트 준비

프로젝트를 진행할 폴더 내에서 아래 작업들을 진행합니다.
우선 yarn 프로젝트를 초기화 합니다.
entry point는 lambda.js로 해주세요. 중요한건 아닌데.. 여기서는 index.js는 만들지도 않을 거에요.
yarn init
프로젝트 초기화가 되면 아래 명령으로 필요한 node 패키지들을 설치합니다.
기본적으로 이렇게 3개만 있으면 됩니다.
yarn add express swagger-ui-express aws-serverless-express

3. 소스파일 작성

2개의 파일이 필요합니다.
  • lambada.js
    • AWS Lambda에 프로젝트를 업로드 했을 때, API Gateway를 통해서 들어온 요청을 받아서 express로 전달할 파일입니다.
  • app.js
    • express가 동작하는 파일입니다.
lambda.js의 코드는 AWS Lambda에서 express 어플리케이션을 구동시키기 위해서 사용하는 일반적인 코드입니다.
// lambda.js
'use strict';

const awsServerlessExpress = require('aws-serverless-express');
const app = require('./app');
const server = awsServerlessExpress.createServer(app);

exports.handler = (event, context) => awsServerlessExpress.proxy(server, event, context);
// app.js
'use strict';

const express = require('express');
const app = express();

const awsServerlessExpressMiddleware = require('aws-serverless-express/middleware');

// swagger-ui-express 미들웨어를 불러옵니다.
const swaggerUi = require('swagger-ui-express');

app.use(awsServerlessExpressMiddleware.eventContext());

// 아래 처럼 작성하면 {API Gateway에서 획득한 주소}/api-docs/v1 으로 Swagger UI web page에 접속 할 수 있습니다.
// Swagger Json 파일은 AWS S3에 업로드 하고 해당 객체에 주어지는 URI를 6번째 인자에 복사해 넣습니다.
app.use('/api-docs/v1', swaggerUi.serve, swaggerUi.setup(null, null, null, null, null
    , '{Swagger Json 파일의 S3 주소}'
));

module.exports = app;

여기까지 진행하면 프로젝트 구조가 아래와 같습니다.
Project Folder
├── node_modules
├── app.js
├── lambda.js
├── package.json
└── yarn.lock

4. Swagger Json 파일을 AWS S3에 업로드

Swagger Json 파일을 AWS S3에 업로드 합니다.
혹시, Json 파일을 직접 작성하시기 전에 예제를 이용해서 테스트 해보고 싶으시다면, S3에 올리는 단계를 건너 뛰시고
Json 파일의 URL을 http://petstore.swagger.io/v2/swagger.json로 사용하시면 좋습니다.
해당 json 파일은 swagger-ui-express에서 제공하는 예제입니다.
S3에 Json 파일을 업로드 하면, 업로드 후에 2가지 작업을 해줘야합니다.
  • 첫번째, json 파일의 접근 권한을 public으로 설정해줘야합니다. 요즘엔 파일을 업로드하고 파일의 '개요'를 보면 '퍼블릭으로 설정' 기능이 있어서 간편하게 public으로 설정이 됩니다.
  • 두번째, json 파일을 업로드한 S3 Bucket의 CORS에 header를 추가합니다. Bucket의 '권한'에서 'CORS 구성'을 아래와 같이 작성합니다. 기본 작성된 것에 딱 한줄 추가됩니다.
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<CORSRule>
    <AllowedOrigin>*</AllowedOrigin>
    <AllowedMethod>GET</AllowedMethod>
    <MaxAgeSeconds>3000</MaxAgeSeconds>
    <AllowedHeader>Authorization</AllowedHeader>
    <AllowedHeader>Content-Type</AllowedHeader>      <!-- <<== 이거 한줄 추가합니다. -->
</CORSRule>
</CORSConfiguration>

5. 프로젝트를 AWS Lambda에 올리고 API Gateway와 연결하기

이 단계는 아래 링크를 참고해주세요.
이 단계만 해도 글이 어마어마하게 길어져서 이전의 포스팅을 안내해드립니다.
제 포스팅 뿐만아니라 제 포스팅을 시작으로 관련 키워드들을 많이 검색해서 자료를 보시길 추천드립니다.
( 링크 : https://walkinpcm.blogspot.kr/2017/08/awsaws-lambda-express-react-application.html )
핵심적인 사항은 아래와 같습니다.
  • Lambda Function을 만들 때, 프로젝트 파일들을 zip으로 압축해서 파일로 Lambda Function에 업로드하고 구성 설정에서 Handler를 lambda.handler로 해야합니다.
  • API Gateway는 아래와 같은 구조로 /{proxy+} 만 만들어주시면 됩니다. CORS도 설정해주시구요.
/
    /{proxy+}
        ANY
        OPTIONS

6. Swagger UI Web Page 접속

제대로 작업이 진행되었다면, 아래와 같이 Swagger UI 화면이 나타납니다.
접속 주소는 API Gateway에서 배포한 후에 생성된 URL에 위에서 설정했던 /api-docs/v1을 붙인 것입니다.



이상으로 Swagger UI Web Page를 만드는 방법을 끝마치겠습니다.
혹시 잘 안되거나 잘못 된 부분이 있다면 댓글 남겨주세요. 최대한 빠르게 확인하고 답변 또는 포스팅 수정/보완 하도록 하겠습니다.
감사합니다~

Tip.
아래 링크에서는 Json 또는 Yaml로 된 Swagger 문서를 바로바로 Swagger UI로 볼 수 있습니다. Swagger 문서를 작성할 때 좋습니다.
(링크 : http://editor.swagger.io )
제 경우에는 AWS API Gateway로 API를 작성했기 때문에 API Gateway의 기능인 '내보내기' 기능으로 Swagger 문서를 획득할 수 있어서 위 링크에 복사해두고 조금 더 다듬는 용도로 사용합니다.

댓글 없음:

댓글 쓰기