MSA 환경에서 API 문서 통합 관리 ( Spring restDocs와 Swagger UI 조합)
MSA 환경에서 API 문서화는 어떤식으로 구성되는지 생각해보자. 현재 프로젝트가 4개의 서비스로 구성되어 있다. 그럼 API 문서도 각 서비스마다 만들어질거고 각 URL 도 다르게 전달해야한다. 현재 프로젝트는 랜덤 포트를 이용하기 때문에 진짜 너무 불편하다!!!!!
이런 API 문서를 하나로 통합하는 방법은 무엇이 있을까?
역시 이미 수 많은 개발자분들이 고민했던 문제였고 해결방법도 제시해놓으셨다...
하나로 통합하는 순서를 정리해보겠다.
1. restDocs를 이용해 테스트 문서 만들기
2. openAPI Spec 추출하기
3. 도커를 이용해 추출한 파일을 합쳐서 Swagger UI 로 보내기
4. 빌드 배포까지 자동화 -> 아직 나도 이 단계까지 가지 못했다.
개발환경은 맥 / 메이븐 / 인텔리제이 / 이미 swagger 환경파일 메이븐 추가 완료한 상태 / 도커 설치된 상태
pom.xml
1. Spring restDocs를 이용해 API 문서 만들기.
test 코드 일부분
테스트 코드를 restDocs 공식문서를 참고하여 작성한다.
2. openAPI Spec 추출하기
이미 아주 좋은 오픈소스가 존재한다고 한다.
https://github.com/ePages-de/restdocs-api-spec 에서 관련 내용을 확인할 수가 있는데 해당 링크에서는 gradle 버전이고 https://github.com/BerkleyTechnologyServices/restdocs-spec 는 maven 버전이라고 한다.
테스트에서 import 수정
MockMvcRestDocumentation
---->>>
MockMvcRestDocumentationWrapper;
바꿔준다.
이후 메이븐 빌드를 해준다
터미널에 mvn install
합친 파일 생성
내가 생겼던 오류
Please refer to /Users/jifrozen/project/Dining-together/Backend/auction/target/surefire-reports for the individual test results.
[ERROR] Please refer to dump files (if any exist) [date].dump, [date]-jvmRun[N].dump and [date].dumpstream.
maven-surefire-plugin
메이븐 빌드를 도와주는 플러그인이라고 한다. 추가했더니 해결됐다.
openapi3.0.json
너무 길어서 일부분만 올린다.
3. 도커를 이용해 추출한 파일을 합쳐서 Swagger UI 로 보내기
도커 실행하고 swagger ui 이미지를 받는다.
docker pull swaggerapi/swagger-ui
위 합쳐진 json 파일을 모두 폴더로 이동시킨다.(openapi-3.0.json 을 이름을 변경시켜 이동시킨것이다.)
docker run -d -p 80:8080 \
-e URLS_PRIMARY_NAME=Swagger \
-e URLS="[ \
{ url: 'docs/api.json', name: 'Swagger' } \2
, { url: 'docs/auction.json', name: ‘Auction’ } \
]" \
-v Josn 파일 모은 폴더:/usr/share/nginx/html/docs/ \
swaggerapi/swagger-ui
Swagger UI 공식문서 참고
URLS는 Swagger UI 에서 보여줄 API 정의 문서 환경변수. 여러개인 경우 JSON 배열형식으로 표현한다.
URLS_PRIMARY_NAME은 첫번째 띄울 문서이다.
localhost 을 치면
선택박스로 선택 가능하다.
이런식으로 통합해서 보인다.
도커부터 restDocs까지 모르는부분이 너무 많아 힘들었다.
이제 자동으로 코드를 push 하면 빌드로 json 파일을 생성하고 json 파일을 하나로 모아 문서로 통합해주는 과정이 필요하다. 이 부분도 나중에 작업이 완료되면 글로 남기도록 하겠다....
참고 문서 👍
공식문서
