[Dev] API 문서 - Swagger-UI 적용

[Bumnote]

📝 작업 내용 및 설명

---

프로젝트를 진행하면서 포스트맨을 사용하여 API 문서화를 진행했었습니다. 그러나, API를 수정하게 되었을 때 포스트맨에 다시 수정된 내용을 반영해야 하는 것에 작은 불편함을 느꼈습니다. 이러한 불편함을 해결하기 위해서 Swagger를 도입하기로 결심했고, 프론트엔드 개발자와 보다 더 원활한 소통을 할 수 있도록 작업 진행 중입니다.

Swagger-UI는 편리하지만, 프로덕트 코드에 Swagger 코드를 적용하게 되면 가독성이 떨어질 수 있다는 단점이 있습니다. 또한, 테스트 기반이 아니기에 100% 정확도를 보장할 수 없을 뿐만 아니라 모든 오류에 대한 여러 가지 응답을 문서화할 수 없습니다. 따라서 추후에는 Test 코드 기반으로 Restful API 문서를 돕는 도구인 Spring Rest Docs 를 활용하여 API 문서 작업을 진행할 예정입니다.

✔️ TO-DO

---

kakao-user-controller

• POST /api/nickname
• POST /api/nickname/validate
• POST /api/logout
• POST /api/agree
• GET /api/mypage
• PATCH /api/mypage
• PATCH /api/mypage/address
• GET /login/callback
• GET /api/user/{id}
   

token-controller

• POST /api/login

lecture-controller

• POST /api/location
• POST /api/lectures
• POST /api/lectures/{id}
• POST /api/home

heart-controller

• GET /api/hearts
• POST /api/hearts
• DELETE /api/hearts
• DELETE /api/hearts/deactivates

기타

---

[ Swagger-UI version ]

• implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

Reference

---

[ Swagger vs Spring Rest docs ]

• https://techblog.woowahan.com/2597/