Swagger를 이용한 백엔드의 효과적인 API명세 전달

사진출처: unsplash
 
 

백엔드가 효과적인 명세 전달 고민

어떻게 하면 좋을까?
 

우선은 백엔드의 입장에서 생각해본다.

• 명세는 코드가 만들어지면서 늘 수정될 수 있다.
• 때문에 명세는 코드와 함께 작업되어야 하고, API 테스트를 위해 즉각적으로 수정되어야 한다.
• 같은 백엔드 팀의 경우에는 직접 코드를 보기에 명세의 부족함을 보완할 수는 있다.
• 반면 프론트 팀으로 넘어갈 때는 이야기가 다르다. 최대한 문서만으로 전달이 되었을 때, 그리고 전달이 가능할 때, 불필요한 소통이 사라진다.

지금까지는 그때그때 백엔드와 프론트엔드가 코딩을 하며 API를 맞춰나갈때마다 일대일로 물어보는 방식이었다.  

불필요한 대화 시간과 에너지가 크게 소모되었으리라.
이런 비효율적인 방법이 아닌, 좀 더 생산적이고 효과적인 방법을 도모하고 싶었다.
 

그간 사용해왔던 API 툴은 Postman API Platform | Sign Up for Free이었다.
불편함을 느낀건 명세를 전달하기 위한 문서작성을 IDE나 텍스트편집기가 아닌 웹 브라우저나 Postman의 자체 클라이언트 앱에서 진행을 해야했다는 점이 가장 컸다.¹
 

또한 문서가 완비되기 전의 상황에서도 프론트 측으로 공유를 하고 싶은데 이 부분에 있어 Postman은 유료 플랜, 즉 비용이 발생하였다.²
 

때문에 새로운 툴을 찾아보다 **Swagger**를 알게되었다.
 

Postman vs Swagger 사용 후기

Postman

장점

• 초보자도 이해하기 쉬운 UI UX
• 편리한 API 테스트
• 잘 만들어진 desktop API Client app

단점

• 팀원간 명세 전달시 비용 발생
• 명세 작성시, 코드 개발자는 IDE 또는 편집기에서 벗어나 작업 진행

Swagger

Swagger의 경우 장단점을 언급하기 전, 먼저 사용방법에 대한 간략한 설명을 한다.
 

사용방법

1. SwaggerHub 이용
   API 개수에 제한이 있지만 무료로도 가능하다.
2. SwaggerUI 이용
   http-server를 사용하여 열람 및 API 테스트 가능
3. SwaggerUI를 프로젝트 코드에 import하여 사용³
   NodeJS의 경우 보통 route단에서 주석+데코레이터 형태로 사용할 수 있다.

장점

• 2, 3번을 사용할 경우 코드 개발자는 IDE 또는 편집기 내에서 API 명세를 그대로 작성할 수 있다.
• 또한 2, 3번의 경우 비용이 발생하지 않는다.
• 3번의 경우 git으로 관리가 가능하기에 팀원간 명세 전달시 편리하다.
• API 명세 문서임과 동시에 API 통신 TEST 까지 가능하다.
• 오픈소스이기에 명세 전달시 주어지는 UI 역시 수정이 가능하다. 팀의 성격이나 전달자의 입맛에 따라 바꿀 수 있다.  

단점

• 어려운건 아니지만, 어쨌든 Postman에 비해 러닝커브가 있다.
• 일단 문법이나 코드형식을 익혀야 한다.

Swagger 적용 이야기

과도기

문법도 맛볼겸 사용방법 3번을 우선 도입했다.
모든 준비와 테스트를 끝내고 막상 전달을 하려고 보니,
프론트엔드 팀이 이를 보려면 백엔드의 깃을 클론하고 DBMS를 비롯한 모든 세팅을 해야만 서버가 돌아가기에 정상작동을 한다.
몹시 불편하지 싶다.
 

1번을 사용해볼까는데, 링크전달이라… ⁴
비공개 프로젝트로 진행하게될 사안도 염두에 두었다.
(물론 불가능한건 아니지만, 비용문제를 간과할 수 없었다.)
 

어떻게든 1번만은 피하고 싶었던지라 이번에는 다시 2번으로 확정짓고 세팅을 했다.
 

그런데 진행간에 문득 백엔드 팀원간의 명세 교류는 어떡하지?란 생각이 들었다.
(이걸 간과한 이유는 현재 진행중인 프로젝트의 백엔드가 나 혼자이기 때문이었다.)
 

한참을 고민하다
2번과 3번의 하이브리드 방법을 모색해보았다.
만약 2번과 3번이 참조하는 swagger.yaml을 하나로 지정을 한다면?
 

간단한 테스트를 통과시키고 이 방법으로 진행하기로 했다.  

SwaggerUI + 프로젝트 코드 주입 방식

미리 언급하지만 2가지 방법을 혼용한 내용임으로,
처음 Swagger를 사용해보기 위해 이 글을 참조한다면 몹시 혼란스러울 수 있다.
따라서 참조된 다른 문서에서 하나씩 실행해보며 작동을 익힌 후 참고하길 권장한다.

별도의 폴더를 route단에 주석으로 넣는 방식은 아래 예시처럼 작성하게 되는데 정말 불편하다.⁵
 

// routes/users.js

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Retrieve a list of JSONPlaceholder users
 *     description: Retrieve a list of users from JSONPlaceholder. Can be used to populate a list of fake users when prototyping or testing an API.
*/
router.get('/', function(req, res) {
  //...
});

이런식으로 데코레이터를 비롯한 주석처리로써 swagger-ui-jsdoc가 코드를 읽을 수 있게 처리하는건데, API별 명세는 한 두개가 아닐뿐더러 자세하게 작성하기 시작하면 수십줄은 훌쩍 넘어간다.
 

즉, 자칫 route파일의 가독성이 몹시 불편하게 될 수 있어 보였다.  

물론 해당 주석부분을 collapse all 처리해도 되지만 그때그때 expand하고 다시 collapse 하는게 역시나 불편하긴 마찬가지다.
 

때문에,
프로젝트 코드의 swagger.js파일의 세팅을 별도의 폴더로 지정하고 SwaggerUI를 프론트단에서도 쓸 수 있도록 js파일이 아닌 yaml파일로 작성하기로 하고, 명세 종류가 많아짐에 따라 가독성 저하로 인한 파일 분기를 모색했다.⁶
 

설치

SwaggerUI 세팅

SwaggerUI는 세팅이 굉장히 쉽다.
 

swagger-api/swagger-ui 코드를 클론하고 dist폴더만 남긴채 모두 지워준다.(나머지는 모두 참고문서)
 

현재시점인 Swagger UI v4.17.1의 dist폴더를 살펴보면 index.html에서,
내가 사용하고자 하는 URL을 지정하는 위치는 다음과 같다.
 

 

// swagger-initializer.js

window.onload = function () {  
  //<editor-fold desc="Changeable Configuration Block">  
  
  // the following lines will be replaced by docker/configurator, when it runs in a docker-container  window.ui = SwaggerUIBundle({  
    url: 'http://localhost:8080/index.yaml', // <= 바로 이부분을 고쳐준다. 
    dom_id: '#swagger-ui',  
    deepLinking: true,  
    presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],  
    plugins: [SwaggerUIBundle.plugins.DownloadUrl],  
    layout: 'StandaloneLayout',  
  });  
  
  //</editor-fold>  
};

저 부분이 앞으로 사용하게 될 SwaggerUI의 html파일이 가르키게 될 나의 Swagger 메인 문서 위치이다.  

나는 dist폴더의 파일들을 적용할 프로젝트 폴더 안 api-docs 라는 폴더를 만들고 그 안에 배치하였다. 그리고 api-docs폴더의 tree는 다음과 같다.

.
├── README.md                <- 이건 후술할 git submodule때문에 생성
├── _build
│   └── index.yaml
├── favicon-16x16.png
├── favicon-32x32.png
├── index.css
├── index.html
├── oauth2-redirect.html
├── swagger                  <- 이 폴더안에 index.yaml을 만들어서 세팅한다. 
│   ├── index.yaml
│   └── user                 <- 내용이 방대함으로 성격에 따라 폴더와 파일들로 분기했다. 
│       ├── signIn.yaml
│       └── signUp.yaml
├── swagger-initializer.js
├── swagger-ui-bundle.js
├── swagger-ui-bundle.js.map
├── swagger-ui-es-bundle-core.js
├── swagger-ui-es-bundle-core.js.map
├── swagger-ui-es-bundle.js
├── swagger-ui-es-bundle.js.map
├── swagger-ui-standalone-preset.js
├── swagger-ui-standalone-preset.js.map
├── swagger-ui.css
├── swagger-ui.css.map
├── swagger-ui.js
└── swagger-ui.js.map

그리고 다음과 같이 index.yaml을 작성해준다.
 

# api-docs/swagger/index.yaml

openapi: 3.0.0  
servers:  
  - description: project_review localhost API document  
    url: http://localhost:8000  
info:  
  version: "1.0.0"  
  title: project_review-API  
  description: The API for project_review  
  contact:  
    name: Inchan Song  
    url: https://github.com/inchanS  
    email: [email protected]  
paths:  
  /users/signup:  
    $ref: "./user/signUp.yaml"    #코드가 길어지면서 지저분해짐에 따라 분기하고 참조했다.
  /users/signin:  
    $ref: "./user/signIn.yaml"

swagger 명세 작성

API 명세의 자세한 내용은 다음과 같은 형식으로 작성하였다.
 

# api-docs/swagger/user/signin.yaml

post:  
  tags:  
    - User  
  summary: 회원 로그인  
  description: 회원 로그인 관련 API  
  produces:  
    - application/json  
  requestBody:  
    description: 회원 로그인시 필요한 사용자 정보 객체  
    required: true  
    content:  
      application/json:  
        schema:  
          $ref: '#/components/schemas/User'  
  responses:  
    200:  
      description: successful operation  
      content:  
        apllication/json:  
          schema:  
            $ref: '#/components/schemas/Success'  
    500:  
      description: Internal server error  
      content:  
          apllication/json:  
            schema:  
              $ref: '#/components/schemas/Error'  
components:  
  schemas:  
    User:  
      type: object  
      properties:  
        email:  
          type: string  
          description: The email of the user  
          example: '[email protected]'  
        password:  
          type: string  
          description: The password of the user  
          example: 'Abcd@1234'  
    Success:  
      type: object  
      properties:  
        message:  
          type: string  
          description: 로그인 성공 메세지  
          example: 'SIGNIN_SUCCESS'  
        result:  
          type: object  
          description: 로그인 성공시 토큰값  
          properties:  
            token:  
              type: string  
              description: 토큰값  
              example: "token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTYsImlhdCI6MTY3ODEyOTY0OX0.eyNOFEZt5xPSakzy4FyGqub9heSZA5FtOZGtWyTI4vg'"  
    Error:  
      type: object  
      properties:  
        message:  
          type: string  
          description: 로그인 실패시 메세지  
          example: '(THIS_EMAIL)_IS_NOT_FOUND'

"scripts": {  
  "test": "cross-env NODE_ENV=test jest --runInBand --detectOpenHandles --forceExit",  
  "build": "npx tsc",  
  "api-docs": "swagger-cli bundle api-docs/swagger/index.yaml --outfile api-docs/_build/index.yaml --type yaml",  
  "predev": "npm run api-docs",  
  "start": "cross-env NODE_ENV=production node dist/main.js",  
  "dev": "cross-env NODE_ENV=develop concurrently \"npx tsc --watch\" \"nodemon -q dist/main.js\"",

그리고 이 파일을 열어볼 수 있는 방법은 다음과 같다.  

Swagger.js파일 적용

이제 방금 세팅한 SwaggerUI에서 사용할 yaml 명세를 Node 서버 안에서도 돌아갈 수 있도록 세팅을 한다.
 

npm 설치

2개의 npm package를 필요하다.

• swagger-jsdoc(js에서 swagger 문서를 읽고 쓸수 있도록 해준다.)
• swagger-ui-express(express 서버에서 SwaggerUI가 돌아갈 수 있게 해준다.)
   

// javascript 사용시,
npm i -D swagger-jsdoc swagger-ui-express

// typescript 사용시 아래 패키지도 "추가적으로" 설치해준다.  
npm i -D @types/swagger-jsdoc @types/swagger-ui-express

swagger.js 세팅

현재 프로젝트의 폴더트리는 대략 다음과 같다.
 

앞에서 모두 처리하였기에 여기서는 2가지만 처리하면 된다.
1. swagger.ts(js) 생성⁷
2. app.ts(js) 코드 추가⁸

swagger.ts(또는 js)를 적당한 위치에 생성하고 다음과 같이 코드를 작성한다.
 

import swaggerJsdoc from 'swagger-jsdoc';  
  
const options = {  
  swaggerDefinition: {  
    openapi: '3.0.0',  // 사용하는 버전을 적어준다. 버전별 문법이 조금씩 상이하다.  
    info: {  
      title: 'Project_review',  // 프로젝트명과 부연정보 기입
      version: '1.0.0',  
      description: 'project_review API with express',  
      license: {  
        name: 'MIT',  
        url: 'http://localhost:8000/api-docs/',  
      },  
      contact: {  
        name: 'Inchan Song',  
        url: 'https://github.com/inchanS',  
        email: '[email protected]',  
      },  
    },  
    servers: [  
      {  
        url: 'http://localhost:8000', // 이건 node서버가 돌아가는 주소!!  
        description: 'local Server',  
      },  
    ],  
  },  
  apis: ['api-docs/index.yaml'],  
};  
  
const specs = swaggerJsdoc(options);  
  
export { specs };

apis: ['api-docs/*', 'api-docs/swagger/*],  

이제 app.ts를 수정한다.
 

import { specs } from './utils/swagger';  // 방금 생성한 swagger.ts파일
import swaggerUi from 'swagger-ui-express'; // npm으로부터 import

// ... 코드 중략

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));  
// '/api-docs'가 라우터 주소이다. 

app.use(router);

// ... 코드 생략

node 서버에서의 SwaggerUI 접속은 ’localhost:8000/api-docs’가 된다.  

거의 다 끝났다.
이제 프론트엔드와 백엔드에게 각각 어떻게 전달을 할 것인가?

• 백엔드의 경우에는 팀 깃 레포 공유로 인해 PR을 할때마다 추가되니 문제될 것이 없다.
• 프론트의 경우에는?? 따로이 레포를 줘야 하나?

git submodule 로 해결

api-docs 폴더를 그대로 git submodule로 새로 만든 레포지토리에 연결을 한다.
나는 “진행중인 프로젝트명-API"라는 이름으로 생성하였고,
다음과 같이 진행하였다.

# submodule 진행할 디렉토리로 이동후, 
$ git init 
$ git remote add origin <새로만든 레포지토리> 

# 그리고 project root폴더로 이동후,
$ git submodule add -b main <새로만든 레포지토리> <submodule 진행할 디렉토리>

# 예시...
$ git submodule add -b main https://github.com/inchanS/project-review-API-docs.git api-docs

그리고

# project root폴더의 위치에서 

$ git submodule status

# 명령하면 연결된 submodule의 내역이 나온다. 

이제 코딩을 진행하며 백엔드 코드는 기존과 같이 커밋과 푸쉬를 자유롭게 진행하고,
 

프론트엔드 측으로 전달할만큼의 API 명세가 update 됐을 때에는,
따로이 submodule 폴더만 해당 레포지토리에 commit, push를 진행하면 된다.
 

그리고 실수로 올라간 push로 인해 불필요한 알림을 최소화 할 수 있도록,
버전 release 태그를 활용하여 여기에만 slack에 webhook 될 수 있도록 세팅을 한다.

그러면 다음과 같이 github의 release로 필터링된 멋진 알림이 가게 된다.
 
 

아쉬운 점

http-server나 node서버 없이도 명세만 볼수 있게끔 완전한 HTML 파일만 추출 할 수 없나 고민중이다.
어찌됐든간에 html파일을 바로 열어볼 수 있는 것과, http-server 명령어를 입력하고 열어볼 수 있는건 사용자 경험에 있어 하늘과 땅차이니까 말이다.
현재 SwaggerUI의 코드가 워낙 복잡(?)해서 건드릴 엄두가 나질 않지만, 차후 시도해볼만하지 않나 싶다.