API 문서 자동화 프로그램...

현재 진행중인 프로젝트에서 모든 API에 대해서 간략한 명세서를 작성해주는 'API 문서 자동화 프로그램'을 만들었다.

 

프로그램을 만든 이유

1. 최신화

=> 이전에 회사를 다니면서 느꼈던거지만 프로그램을 위한 문서들은 항상 최신 상태를 유지하기 어렵다. 왜냐하면, 사람이 누락하는 경우가 종종 생기기 때문이다. 프로그램을 위한 문서는 여럿 존재한다 모든 사항에 대해서 문서화를 다 하기도 힘들고, 새로운 인력이 해당 프로그램을 관리하게 되면 문서 존재 유무조차 모르는 경우가 생긴다. 이러한 부분에 있어서 'API 문서 자동화 프로그램'을 실행하게 된다면, 단 1번의 실행으로 항상 최신 상태를 유지할 수 있는 것이다.

 

2. 시간 낭비

=> 프로그램을 하나 만들고나서 항상 문서를 신경 써줘야 한다는 사실이 정말 귀찮다. 사실 단순 문서 1개일지라도 이러한 요소들이 하나씩 늘어나다보면 개발을 하고나서 신경 써야할게 5가지 이상 혹은 10가지 이상이 생겨나기도 하는 법이다. 확실히 나는 이전 회사에서 SM 업무를 주로 하다보니 더욱 더 그런 요소를 많이 느꼈다. 시간낭비 하기 싫었다.

 

이러한 이유들을 종합해보면 나는 시간을 낭비하기 싫고, 프로그램은 항상 최신화하고 싶었기 때문에 API 문서 자동화 프로그램을 만들었다.

 

만든 방법

1. 프로젝트 폴더에 있는 router에 존재하는 모든 소스코드를 읽는다.

2. 모든 글자들을 단어 단위로 잘라서 리스트에 담는다. (공백 제거)

 - 주석은 공백제거 하지 않음.

3. 모든 단어를 담은 리스트를 처음부터 끝까지 탐색한다.

4. router를 마추지면 API에 대한 요소들을 담는다.

 - method와 url에 대한 정보

 - response 값들에 대한 정보

 - 해당 라우터에 대한 정보를 요약한 주석정보도 불러옴. 여기에는 title이나 description request 요소를 담는다.

5. '4'에서 적은 데이터들을 문서에다가 '쓰기'한다.

 

 

실제 소스 파일 예시) 

/**
 * @title : 고객 정보 수정
 * @abstarct : 고객 정보 수정
 * @description : 머루ㅏㅓㄴㅁ아뮹라뮨류밀유
 * @request : {
 * _id : ObjectId
 * } 
 */
 router.post("/edit_customer", auth, async (req, res) => {
    var result = await customer01Service.Customer01EditCustomer(req);
    if(!result){
        return res.status(403).json({code:"EDIT_CUSTOMER_ERROR01", message : "수정 실패"});
    }
    return res.status(200).json({code:"EDIT_CUSTOMER_SUCCESS", message : "수정 완료"});
});

 

1. 위 소스코드에서 router를 만나기 직전에 주석처리된 정보는 따로 특정 변수(routerInfo)에 담아둔다. 바로 문서로 쓰지 않는 이유는 해당 정보가 router를 위한 정보인지 아닌지 정확하게 판단할 수 없기 때문이다.

2. router를 마주치면 routerInfo에 담아둔 API 정보들을 가져와서 파일에 쓴다.

3. 'post'(method)와 "/edit_customer"(url) 정보를 파일에 쓴다.

4. 이제부터 res 혹은 response를 만나면 모든 해당 함수들에 대한 정보를 모두 파일에 쓴다.

 

 - res.status(403).json({code:"EDIT_CUSTOMER_ERROR01", message : "수정 실패"});

 - res.status(200).json({code:"EDIT_CUSTOMER_SUCCESS", message : "수정 완료"});

 

이리하여 완성된 실제 API 문서는 다음과 같다.

문서가 생겨먹은게 조금 조잡해 보일지도 모른다. 내가 봐도 조잡하다. 그런데 API 문서는 사람을 위해서 존재해야 한다. 문서를 위해서 사람이 존재하면 안되는게 내 생각이다. 비록 이 문서가 조잡해 보이기는한데, 한 눈에 모든 정보들을 받아보기 편하다. 나는 엑셀로 이러한 문서를 만들어서 여러 시트에 나눠서 관리하는게 더 보기 불편하다. 어쨌든 이 문서는 나를 위한 문서이니까 이렇게 만들었다.

 

프론트엔드 API 요청 시, 상태에 따른 분기 처리를 위해서는 API 문서는 필요하다. 만약에 API 문서가 없다면 백엔드 소스코드를 직접 열어서 response를 한 개씩 모두 찾아서 상태 처리를 해줘야 한다. 그리고 모든 response에 대해서 처리를 제대로 해줬는지 검증하기도 번거롭다. 이러한 면에서 API 문서가 있다면 프론트엔드에서 해야할 작업이 명확하기 때문에 손쉽게 작업할 수 있는거다. 지금 API 문서에서 보면 2개의 response가 있지만, 만약에 10개의 response가 있다면 어떨까? 백엔드 소스코드를 직접 훑어보면서 상태처리 하는 것은 비효율적이다.

 

사실 여기서 프로그램을 더 업데이트해서 더 보기 좋게 바꿀 수는 있다. 하지만, 이 프로그램을 수정하기 위해서 들어가는 '비용'이 과연 옳은지 고민을 해봤다. 그 결과는 당장에 더 이상 API 문서 자동화 프로그램을 업데이트 할 필요는 없었다. 나중에 프로그램이 더 커지거나, 협업할 누군가와 함께 이 문서가 보기 불편하다면 프로그램을 수정할 생각이다. 하지만, 이 문서를 수기로 직접 수정할 생각은 절대 없다. (단, 필요한 상황이면 해야겠지만...)

 

장점

1. 항상 최신화

2. 시간 절약

3. 프론트엔드에서 API 연동 작업 시 해야할게 무엇인지 바로 판단 가능 (이거는 API 문서 장점인듯...)

 

실제로 내가 수기로 직접 계속 관리하는 것보다는 더 편했다.

 

단점

1. router 함수 내에 존재하는 response만 확인 가능

 - router에서 더 세부적인 함수 내에서 response를 던지는 경우라면 그러한 값들을 찾기 어렵다. 프로젝트를 하면서 느낀거지만, 특정 기능에 대한 response는 모두 router 함수 내에서 던지도록 정의했다. 나 혼자만 세운 규칙이기 때문에 이런 프로그램을 쉽게 만들 수 있었던게 확실하다.

2. response를 던져주는 변수에 대한 정보를 정확하게 확인할 수 없음.

 - 당장 혼자서 작업하기에 response 변수에 대한 정보를 정확하게 적어줄 필요는 없었다. 그래도 API 문서인데, response에 대한 값을 모두 다 가지고 있는게 맞긴하다. 이 부분에 대한 프로그램 업데이트는 필요할 것 같다. resonse 해주는 변수에 대한 정보를 json 파일에 저장해두고 필요할 때마다 치환해주는 방법이라든가... 아니면 실제 음... 잘모르겠다. 내가 생각한건 json 파일에서 변수에 대한 내용을 치환하는 정도로만 생각해봤다.

 

결론

이러한 프로그램이 있어서 혼자서 프론트엔드와 백엔드 모두를 작업하기에는 편하다. 그런데 불완전한 앱인건 사실이다. 그러니 프로그램 업데이트는 필요하다. 그래도 당분간 혼자서 작업할 때 백엔드에서 API 완성 후, 프론트엔드에서는 API 문서만을 보면서 작업이 가능해졌다는 점이다. 만약에 이 API 문서를 자동화하지 않았다면 API 문서를 적지 않았을거다. 그러면 프론트엔드에서 response 각 상태에 따른 처리를 해주기 힘들었을거다. 왜냐하면 내가 백엔드 소스코드를 새롭게 뜯어보면서 response 값들을 하나씩 다 찾아가면서 확인해야 하기 때문이다.

 

이 정도의 API 문서를 자덩화만 하더라도 프론트엔드와 백엔드를 혼자서 작업하기는 많이 편해졌다. 상태에 따른 분기처리를 하기 쉽기 때문이다. 물론 협업을 위해서라면 더 많은 정보가 담겨야 하는게 사실이다. 혼자니까 이 정도만으로도 편하다는 말이다. 협업을 한다면 아무래도 request와 resposne 정보에 대해서 조금 더 명확하게 정의를 해줄 필요는 있다. 혹시나 나중에 협업이 필요하면 API 문서 자동화 프로그램을 업데이트 하는게 중요하다.