중계서비스 Swagger 도큐먼트 툴 적용 + 단점 보완

이번 포스팅은 혹시나 다른 방법을 찾으신 분은 댓글로 공유 부탁드립니다!

Contents

0.  "중계 서비스" 관점에서 API 문서화가 필요한 이유

1.  Swagger 채택 이유

    1-a. 적용을 위한 비용이 상대적으로 낮습니다.

    1-b. Swagger에서 Spring Rest docs로 전환하는 케이스가 많습니다.

    1-c. 저렴한 전환 비용

2. Swagger : 단점과  보완 전략

    2-a.  검증이 되지 않은API의 노출

    2-b.  서비스를 위한 코드와 문서화 코드의 결합

    3.  서비스 코드와 문서화 코드의 분리 방법 

    3-a. Swagger의 동작 원리

    3-b.  적용 순서

3. 마치며...

 

---

0.  "중계 서비스" 관점에서 API 문서화가 필요한 이유

 

최근 프로젝트에 문서화 툴을 적용하자는 제안을 받았습니다.

물론 개발 조직에서 문서화 툴이 있어야 하는 이유들은 많겠지만 중계 서비스에서는 왜 문서화 툴이 필요한지 고민해봤습니다.

서비스 관점에서 보자면 주제가 배달 서비스 중계서버인 만큼 사장님 앱, 배달 대행사 앱, 고객님 앱, 다른 배달의민족 서버 등 여러 주체들이 저희 API를 활용해야 하기 때문입니다.

 

---

1.  Swagger 채택 이유

저희 프로젝트에서는 Java, SpringBoot를 사용하고 있습니다.

Java, Spring 환경에서 자주 사용되는 툴로는 Swagger, Spring Rest Docs 가 있는데요,

저는 이 두 가지를 비교해보고 Swagger를 선택했고 이유는 다음과 같습니다.

 

https://taetaetae.github.io/posts/a-combination-of-swagger-and-spring-restdocs/

1-a.  적용을 위한 비용이 상대적으로 낮습니다.

여기서 비용은 코드 작성 시간, 툴을 학습 시간, 그리고 이후 자동화 설정을 위한 시간들을 의미합니다.

초기단계의 프로젝트에서 Swagger의 적용-용이성은 무시할 수 없습니다.

Spring Rest Docs에서 Swagger로 전환하는 비용보다 방향이 반대일 경우의 비용이 훨씬 저렴합니다.

 

1-b.  Swagger에서 Spring Rest docs로 전환하는 케이스가 많습니다.

이 말을 직설적으로 받아들이면 Spring Rest Docs 가 더 강력한 기능을 제공한다는 뜻인데요.

반대로 생각해보면 Swagger의 민첩성을 입증하는 이야기가 됩니다.

 

추가적인 내용들은 Rough 하게 프로젝트 이슈에 정리되어있습니다.

REST 도큐먼트 툴 적용 · Issue #28 · f-lab-edu/in-bob-we-trust

 

---

2. Swagger : 단점과  보완 전략

https://blog.yaware.com/monitoring-pros-and-cons/

 

 

Swagger 의 주요 단점들입니다.

• 검증이 되지 않은 API의 노출
• 프로덕션 코드와 문서화 코드의 결합

 

어떻게 하면 이 단점들로부터 오는 피해를 줄일 수 있을까요?

 

2-a.  검증이 되지않은 API의 노출

검증이 되지않은 API 가 노출될 수 있다면 API를 최대한 검증해야 합니다.

저희 프로젝트에서 테스트는 필수입니다.

또한 지속적 배포 프로세스에 Github Action을 활용한 Test validation 이 포함되어있습니다.

여기서 추가로 테스트에 더 신경 쓰면서 "검증이 되지 않은 API의 노출" 리스크를 최소화할 수 있습니다.

사실상 Swagger가 코드에 없는 API를 노출하지는 않으니까요.

 

2-b.  서비스를 위한 코드와 문서화 코드의 결합

Controller 메서드에 어노테이션을 조금씩 추가하다 보면 금세 메서드 하나가 크리스마스트리처럼 되어버리기 때문에 개발 과정에서도 치명적인 부분입니다.

프로덕션 코드에서 완전히 분리되지는 않겠지만 분리를 위해 최대한의 노력은 해야 합니다.

그래서 스프링에서 swagger 가 적용되는 원리를 활용해서 일정 수준의 논리적 분리를 적용했습니다.

적용 방법은 추가로 아래에서 예제 코드와 함께 상세하게 다루겠습니다.

 

 

---

3.  서비스 코드와 문서화 코드의 분리 방법 

 

2-b. 에서 언급한 상세 적용 방법을 소개하겠습니다.

 

3-a. Swagger의 동작 원리

Swagger 의 작동원리를 살펴보기 위해 자주 사용하는 @ApiOperation 어노테이션을  한번 보겠습니다.

 

위 어노테이션은 메서드에 지정되며 런타임까지 유효합니다.

Swagger의 설정 또한 스프링의 Configuration 빈으로 스프링 컨테이너에 등록합니다.

그렇다면 "문서화 관련 어노테이션들도 타입 기준 스캐닝을 하겠구나"라는 추측을 해볼 수 있습니다.

 

3-b.  적용 순서

• DeliveryController 가 있습니다.
• DeliverController 가 DeliverControllerSwaggerDoc 인터페이스를 구현하게 합니다.

 

 

• DeliveryControllerSwaggerDoc 인터페이스를 생성합니다.
• ***인터페이스 이름은 자유이지만 최대한 명시적인 이름으로 해주시기를.
• DeliveryController 가 사용하는 모든 핸들러 메서드들의 추상 메서드들을 인터페이스에도 붙여 넣습니다.
• 메서드 별로 필요한 Annotation 들을 적용합니다.

 

 

• ( Optional )  Swagger 어노테이션들이 적용될 인터페이스들은 Swagger 설정 Bean의  하위 패키지에 위치해두면 어떨까... 생각해봅니다. 

 

 

---

3.  마치며...

이렇게 저희 프로젝트에 문서화 툴 Swagger 적용 사례를 소개해드렸습니다.

이번 포스팅 관련 소스코드는 프로젝트의 "feat-REST-도큐먼트-툴" 브랜치를 확인하시면 되겠습니다.

 

 

읽어주셔서 감사합니다.