Swagger 도입

[Choi-JJunho]

Swagger를 도입하는 이유: 동아리에서 API 문서화 도구로 Swagger를 사용해왔고 클라이언트 즉에서도 이에 대한 매뉴얼을 만들어 숙지하고 있는 상황이다. 동아리 운영 관점에서 Swagger를 사용하지 않을 이유가 없다.

기존에 마이그레이션을 마친 후 swagger를 도입하려고 했으나 지난 온보딩을 진행하며 생각해본 결과 Swagger 작성까지 포함해야할 것 같습니다.
나중에 한꺼번에 작성하다보면 작업단위도 크고, 누락되는 내용이 있을 수도 있다는 의견입니다.

이에 API가 더 많이 구현되기 전에 Swagger를 도입하고자 합니다.

도입 . 아래 두가지 방식이 떠올라 고민이 됩니다.

1. 기존 방식과 동일하게 프로덕션 코드에 Swagger 코드 적용

• 간단하다

2. 인터페이스로 분리하여 Swagger 코드 선언

• 문서화에 대한 코드를 분리해서 볼 수 있다.
• 참고 Repository

각자의 장단이 뚜렷하기보다는 취향차이가 큰 것 같습니다.
Swagger 도입 및 구현 방식에 대한 의견 부탁드립니다.

[songsunkook]

Swagger 도입을 찬성합니다.
클라이언트 입장에서 API 명세를 확인하기에 현재로써 이만한 도구가 없다고 생각합니다.

Swagger 구현 방식에 대해서는 개인적으로 2번 방식이 적절해 보입니다.

기존에는 1번처럼 프로덕션 코드에 함께 문서화가 진행되다 보니 한 곳에 관련 정보가 응집해 있어 파일을 오갈 필요 없이 내용을 이해할 수 있어 좋았습니다. 하지만 문서 정보가 프로덕션 코드보다 길어지고 스크롤이 과하게 필요하여 코드를 읽기가 오히려 힘들어질 수 있다고 판단했습니다.

새로 제안해주신 2번 방식으로 진행한다면 문서와 코드 몸체를 한 번에 보기는 힘들 수 있지만, 문서화와 로직에 대한 관심사의 분리가 이루어져 가독성은 높아질 것이라고 생각합니다.

[daheeParkk]

저도 API 작업과 Swagger 작성을 동시에 하는 게 좋다고 생각합니다.

방식은 2번이 좋을 것 같습니다. 기존 1번 방식은 프로덕션 코드에 Swagger 코드가 많아 보기 불편했는데, 2번 방식을 사용하면 분리가 돼 보기 편할 것 같습니다.

[xhdtn8070]

Swagger 도입을 찬성합니다!
이번 기회에 인터페이스를 활용하여 Swagger 문서를 분리하는 방법에 대해 알게 되었습니다.
이 방식을 도입하면 API 문서화의 가독성과 관리가 크게 향상될 것으로 생각합니다.

유지보수 측면과 확장성도 큰 이점이 될 것 같아요. 온보딩 할때도, 컨트롤러와 doc이 분리되서 더 쉽게 전달해줄 수 있을 것 같네요.
많이 배웠습니다!