#1 API 공유

이태의·2022년 9월 7일
1

협업에관하여

목록 보기
1/1

이 이야기는 최소 NN년 간 팀플을 피해온 나의 자전적 이야기이다.

협업에 관하여


요즘 시간을 거꾸로 살고 있어서 팔자에도 없던 팀 프로젝트를 하게 되었다.
가끔이었지만 개발 일을 할 때는 거의 혼자 일을 할 때가 많아서 팀으로 일하는 것은 매우 신선한 일이었다.

특히 100% 온라인으로 협업?!
'이게 가능할까?'하는 의문이 들었다.


프론트 지원자가 대부분일 거라는 (그래서 내가 백엔드를 하게 될 거 같다는) 당초의 예상과는 다르게 팀원 6명 중 백엔드 지원자가 2명이었고 나는 어느 쪽이든 상관없다는 쪽이어서 프론트를 맡게 되었다.

팀장은 백엔드 담당이었는데 프로젝트 경험이 한 번있다고 했고 백엔드는 처음이라 그런지 백엔드만도 소화하는데 약간의 부침이 있어보였다.
그래서 그런지 전체적인 그림을 같이 그리는 게 아니라 백은 백끼리, 프론트는 프론트끼리 알아서 하라는 느낌으로 흘러갔다.

여기서 1차적인 문제가 발생했다.
초반에 API를 공유하고 전체 틀을 잡아가는 방식으로 했어야 했는데 다들 처음인데다가 프론트와 백의 소통이 거의 없이 진행되어, 결국에는 프로젝트 2/3 시점에 API가 공유되고 프론트엔드 소스를 전면 수정 후 테스트를 진행하였다.

그렇다면 올바른 순서는 무엇이었을까?

  1. 일단 전체 흐름과 구조 등은 같이 파악하는 것이 좋았을 것 같다.
    나중에 보니 각자 파악한 정도가 너무 달랐다. 요구사항 이해도, 코드 이해도, 테스트도구 사용방법, GIT 사용 방법, 심지어는 프로젝트 중반까지도 로컬 서버 실행 조차 못하는 팀원도 있었다.

  2. 기본 API 필드, 메소드명은 초반에 명명규칙을 정하고 가능한 한 확정한다.
    아예 수정이 없을 수는 없겠지만 대원칙 안에서 정하여 변경을 최소화한다.

  3. 이건 맞는 방법이 아닐 수도 있는데 매우 급한 프로젝트에 한하여 풀스택 또는 공통 개발자의 경우에는 기본적으로 먼저 commit & push 할 수 있도록 하고 그 소스를 다른 팀원들이 pull 하도록 해야 할 듯하다.


나는 먼저 개발이 끝났는데 협의가 제대로 안 되서 이를 dev 브랜치에 적용하지 못 하고 팀원들이 개발 진행될 때까지 (중간에 몇 번이나 다른 소스 및 필드 등이 변경되어) 내 소스를 그에 맞춰 변경하여야 했다. (당시 git에 익숙치 않아서 수동으로...)
이것만 아니었어도 더 많은 시간을 기능 개발이나 리펙토링에 투자할 수 있었을텐데...
(개발 시간보다 소스 관리에 시간을 더 많이 투자한 것 같다.)

이 부분은 뒤에 다룰 git 과 관련된 이야기이기도 하다.
팀원들이 전반적으로 git 에 익숙하지 못하다보니까 그 부분을 조율하지 못 하고 이로 인해 비효율이 발생한 것이다.



일단 오늘의 주제인 API 공유로 돌아가서 Swagger에 대해 알아보자.

이번 프로젝트에는 스웨거를 적용하지 않았다. (몰라서 안 한 거지만)
스웨거는 단기 프로젝트에는 적합한 도구가 아니다.
그냥 라이브러리 몇 개 설치한다고 마법같이 API 명세가 만들어지는 것이 아니므로.
(난 그럴 줄 알았... 사기당했....?)

그러나 비교적 간단하고(?) 직관적으로 API를 명세화 할 수 있고
프론트와 백이 실시간으로 테스트 도구를 공유할 수 있다는 장점이 있으며
postman 등 별도의 테스트 도구가 필요 없다는 점이 효율적이다.
다음번 프로젝트에는 초기부터 도입해볼까 생각 중이다.
말 한 번 잘못 꺼냈다가 일이 늘어날 수도 있겠지만....


Swagger 간단 정리


1. 환경: node.js(npm or yarm), express, swagger-ui-express, swagger-jsdoc, nodemon

(일단 간단한 라우터 미적용 버전을 기준으로)

2. 기존 프로젝트에 설치되어 있지 않은 라이브러리만 설치한다.

npm install --save swagger-jsdoc swagger-ui-express express nodemon

3. app.jsswagger-jsdoc 의존성을 추가하고 api 메소드에 @swagger 주석을 단다.

https://github.com/Surnet/swagger-jsdoc/blob/v7/docs/FIRST-STEPS.md 참고

// 3-1
import swaggerJsdoc from 'swagger-jsdoc';

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Hello World',
      version: '1.0.0',
    },
  },
  apis: [`${__dirpath}/app.js`],
};

const swaggerSpec = await swaggerJsdoc(options);
// 3-2
/**
 * @swagger
 *
 * /login:
 *   post:
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         in: formData
 *         required: true
 *         type: string
 *     ... 더 들어가야 하지만 생략...
 */
app.post('/login', (req, res) => {
  // Your implementation comes here ...
});

4. app.jsswagger-ui-express 의존성을 추가하고 api-docs와 swaggerSpec를 연결한다.

import swaggerUi from 'swagger-ui-express';

// 3-1 소스 맨 아래에 추가
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

5. api-doc로 접속하여 api를 확인한다.

url:port/api-doc
ex) http://localhost:5001/api-docs


참고자료

profile
즐거운 개발자

0개의 댓글