MSA: Swagger UI로 API 문서 통합 프로세스 (1) Rest Doc을 사용해도 Swagger를 사용해도 Swagger UI로 모아 주기
Index
1: 독립형 Swagger UI 서비스
2: 도커 컴포즈 파일
3: Rest Docs를 Open API로 정적 배포(Gradle Task)
4: Web Config(CORS) 및 Security Config
Open API 문서 통합
권하는 목적은 여러 프로젝트의 문서를 한데 모으는 거지만, 그냥 Rest Docs로 작성한 걸 Swagger UI로 볼 수 있는 점도 이번에 포스팅할 방식의 장점이다.
| 단일 프로젝트 | 여러 프로젝트 |
|---|---|
| Rest Docs 등 원하는 문서화 도구로 작성한 문서를 Swagger UI로 볼 수 있다. | 여러 서비스(서버 애플리케이션)가 작성한 Open API 문서를 하나의 Swagger UI가 통합해서 보여줄 수 있다. |
간단히 검증용으로 만들어 볼 때는 단일 프로젝트에서 만들어 보면 된다.
구성
API 문서 통합을 위해 Swagger UI 서비스를 독립적으로 실행한다.
이 프로세스는 각 마이크로 서비스가 제공하는 Open API 문서를 모아서 제공한다.
이 프로세스는 Rest Doc 사용 여부 등과 무관하게 Open API 문서를 제공받을 뿐이므로, 여러 마이크로 서비스가 각각 그 문서의 생성에 어떠한 도구를 사용하였는지는 신경쓰지 않는다.
그림에서처럼 각 서버 애플리케이션과 구분되기 때문에 다른 처리가 없다면 CORS 설정을 해 주어야 한다.
스프링 부트 Rest Docs
스프링 부트 진영에서 주로 고려하는 단일 애플리케이션 API 문서화 도구는 Swagger와 Rest Docs다.
주로 언급하는 차이점은 테스트 동반 여부다.
Swagger vs Rest Docs
문서화(Test 여부)
| Swagger | Rest Docs |
|---|---|
| 테스트 없이 문서 제공(편의성) | 테스트를 통과한 API만 선별해서 문서 제공(문서의 신뢰도). |
| 대신 프로덕션 코드에 어노테이션 덕지덕지 붙어서 소스코드가 안 이쁨. | 프로덕션 코드와 문서화 코드가 분리되고, 테스트 코드에 문서화 코드를 붙이므로 소스 코드가 유지됨. |
| 편의성에 의해 채택율 높음. | 편의성이 좋지 않아 채택 후에도 다시 Swagger로 전환하는 경우가 적지는 않음. |
만약 Rest Docs 사용 시 테스트 코드를 먼저 작성해 놓고 이것을 통과할 때까지 프로덕션 개발을 하고 있다면, 테스트 커버리지 100%가 나오는 시점에 문서가 땋 태어나니까 좋은 기분은 만끽할 수 있겠다. 다만 작업 순서를 반대로 해서 코드를 먼저 쓰고 테스트 코드를 나중에 짜면 문서화가 여간 귀찮을 듯하다.
팀에 따라 작업 습관이 다를 것이고 TDD에 대해 지향과 지양으로 의견이 나뉠 수밖에 없다.
다만 Rest Docs를 하려면 DTO를 미리 작성해 놓듯이, Rest Docs 코드를 먼저 작성해 놓으면 그 뒤로는 소스코드 개발만 신경을 쓰면 돼서 좀 나을 수 있다.
UI
| Swagger UI | Rest Docs UI |
|---|---|
| UI로 이것을 쓰면 페이지에서 바로 API를 쏴 볼 수 있어서 편하다. 그리고 예쁘다. | UI로 이것을 채택한다면, Swagger UI에 비해 예쁘지 않고, API 확인은 포스트맨 등을 따로 이용해야 한다. |
테스트 여부는 취향이 좀 갈릴 수 있는데, UI는 대체로 Swagger UI가 편의성도 심미성도 인기를 꾸준히 끄는 듯하다.
