Project 문서화에 대해서...

01 Jun 2022 project spring-rest-docs docker

하나의 프로젝트를 시작하게 됨에 따라 고민해야하는 것들이 생긴다.
기본적으로 어떤 언어를 쓸 것인지? 어떤 프레임워크를 쓸 것인지 등….
그 외에도 외부와 연동해야하는 시스템을 만드는 것이라면 문서화는 필수적인 요소가 될 것인다.
이번에 진행한 프로젝트에서 문서화를 어떻게 진행했고, 어떤 고민들을 했으며 어떻게 풀어나갔는지 적어보려고 한다.
어떤 식으로 문서를 제공할 것이냐?
작성하는데 드는 비용을 줄이면서, 효과를 키우고 싶었다.
- 평소에도 스웨거보다 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 문서를 제공할 수 있다. 허나 프로젝트 진행 상황이나, 협업 상황들도 고려가 필요한 부분이 있다. 그래서 우린 익숙하면서도 효과가 좋은 방향을 찾아서 도입했고, 현재도 잘 유지하고 있다.
- 일단 테스트를 성공해야하므로, 신뢰가 가는 부분이 너무 좋다.
단, 다른 신규 입사자가 해당 시스템을 적응하는데 부담이 없도록 문서화를 잘 해놔야할 것 같다!
- 아직 이 부분은 작업 중…

Project 문서화에 대해서...

Related Posts