Project 문서화에 대해서...

  • 하나의 프로젝트를 시작하게 됨에 따라 고민해야하는 것들이 생긴다.
  • 기본적으로 어떤 언어를 쓸 것인지? 어떤 프레임워크를 쓸 것인지 등….
  • 그 외에도 외부와 연동해야하는 시스템을 만드는 것이라면 문서화는 필수적인 요소가 될 것인다.
  • 이번에 진행한 프로젝트에서 문서화를 어떻게 진행했고, 어떤 고민들을 했으며 어떻게 풀어나갔는지 적어보려고 한다.

  • 어떤 식으로 문서를 제공할 것이냐?
  • 작성하는데 드는 비용을 줄이면서, 효과를 키우고 싶었다.
    • 평소에도 스웨거보다 rest docs 를 선호하기는 했다.
    • 프로덕션 코드에 추가하는 것이 아닌, 테스트 코드에 추가가 되고, 테스트가 성공해야만 문서가 생성되기 때문에 많은 장점이 있다고 생각했다.
  • 초기 세팅할 때, @WebMvcTest 를 사용할 경우 제대로 컨텍스트 뜨지 않았다. 여럿이 커밋하고 수정이 빈번하게 발생하고 있었다. 수정하면서 작업하기 어려울 것이라 판단하고 일단 컨텍스트를 다 띄우는 방향으로 먼저 작업을 시작했다. (@SpringBootTest)
  • 그렇게 작업을 하고 3일정도 후에 싹 replace 하고 여럿이 작업하던 부분들을 싹 머지하고 나서 전체 수정을 거쳤다. 그리고 나서 의도한 방향대로 컨텍스트를 수정했고, 기대했던 것 처럼 테스트 시간도 단축되었다.

  • 테스트를 동작시키면, 테스트시 생성된 파일들을 adoc 기반으로 html 들이 생성되는데 예전 프로젝트 혼자 진행할 때는 github static page 기능을 사용해서 특정 브랜치에 머지하여 문서들을 제공했었는데, 그렇게되면 개인들이 커밋한 결과를 머지할 때 html 파일 충돌을 피할 수 없게 된다.
  • 대안으로 ci 가 동작하면 자동으로 파일을 생성하여 static page로 복사해서 제공하려고 했으나…
    • ci 서버에서 특정서버로 생성된 html 파일을 보낼 순 있었으나, kubernetes 환경에서 사용하기는 어려움이 있어서 dockerfile 을 이용해서 테스트를 동작시킨 후에 copy 후에 nginx 로 제공하는 작업을 진행했다.
      • 작업하는데… 10분 정도 걸린 것 같다. 나중에 더 좋은 방법이 있으면 대체하기 위해서 문서제공용 내부 도메인을 발급해놨다.
  • dockerfile
    • https://hub.docker.com/_/nginx
FROM nginx

COPY nginx/nginx.conf /nginx/conf/nginx.conf
COPY api/build/asciidoc/html5 /var/www/html/

CMD ["nginx", "-g", "daemon off;"]
  • nginx.conf
    http {
    ...
      server {
          listen 80;
    
          	root /var/www/html/;
    
              location /health {
          	    return 200;
              }
    
          	location / {
                  	    index index.html index.htm;
              }
      }
    }
    
  • 다양한 방식으로 api 문서를 제공할 수 있다. 허나 프로젝트 진행 상황이나, 협업 상황들도 고려가 필요한 부분이 있다. 그래서 우린 익숙하면서도 효과가 좋은 방향을 찾아서 도입했고, 현재도 잘 유지하고 있다.
    • 일단 테스트를 성공해야하므로, 신뢰가 가는 부분이 너무 좋다.
  • 단, 다른 신규 입사자가 해당 시스템을 적응하는데 부담이 없도록 문서화를 잘 해놔야할 것 같다!
    • 아직 이 부분은 작업 중…

Related Posts