📚 개발과 소통, Swagger 하나로 끝냅니다

안녕하세요 makeviibe 입니다.

​

✅ 왜 API 문서화가 중요할까?

서비스 개발에서 프론트엔드와 백엔드는 API를 기준으로 연결됩니다.

또, 외부와 연동하는 서비스라면 제3자 개발자도 API를 이해해야 하죠.

그런데…

• “이 API가 어떤 데이터 받을 수 있지?”
• “응답 형식이 바뀐 거 같은데?”
• “예전에는 잘 됐는데 지금은 왜 오류지?”

이런 말이 오갈 때마다 실시간 문서를 찾아보기 어렵다면

협업은 혼란, 유지보수는 고통으로 바뀝니다.

그래서 makeviibe 팀은 Swagger를 이용한 API 문서화를 모든 프로젝트에 적용하고 있습니다.

---

🛠️ Swagger가 뭐예요?

Swagger는 백엔드에서 만든 API를 자동으로 문서화해주는 도구입니다.

정확히는 OpenAPI 스펙을 기반으로, API 명세를 웹페이지 형태로 자동 생성해 줍니다.

개발자는 코드를 주석만 잘 달면 되고,

다른 팀원은 웹 브라우저로 보기만 하면 됩니다.

---

🌟 Swagger의 장점

---

🔍 어떻게 사용하나요?

makeviibe 팀은 Spring Boot + Kotlin 환경에서 Swagger를 사용하고 있으며,

보통 springdoc-openapi 또는 Swagger 3.x 를 활용합니다.

💡 예시 코드 (Kotlin + Spring)

→ 위 코드를 작성하면 Swagger UI에 다음 정보가 자동으로 표시됩니다:

• /api/users/{id}
• GET 방식
• 파라미터 설명
• 응답 형식

---

💻 실제 사용 화면

<API 목록>

<API 상세 내용>

<Request, Response schema>

Swagger UI는 다음처럼 구성됩니다:

• 요청 메서드/경로 표시 (GET, POST, PUT 등)
• 입력 값 예시, 설명, 유효성 체크 정보
• 응답 형식과 예시 값
• [Try it out] 버튼으로 실제 요청 테스트 가능

---

🧠 클라이언트가 이해하면 좋은 포인트

• 개발자와의 소통 시, “API 문서” 링크만 전달해도 모든 정보를 확인할 수 있음
• 수정 사항이 있으면 바로 문서에 반영됨 (따로 설명 필요 없음)
• 서비스 기획자도 흐름을 이해하기 쉬움 (예: 어떤 데이터가 오고 가는지)

---

✍ makeviibe 팀의 적용 방식

• 모든 API는 Swagger에서 자동 명세화되도록 설계
• 비로그인 사용자도 일부 API 문서를 확인할 수 있도록 설정
• 관리자용/앱용/외부용 API를 구분해 명확하게 구성
• Swagger UI를 외부 테스트용으로 제공하거나, 내부 문서 링크로 활용

---

📌 마무리

Swagger는 단순한 "문서 도구"가 아닙니다.

개발팀 간의 신뢰를 높이고, 클라이언트와의 커뮤니케이션을 매끄럽게 하는 핵심 도구입니다.

특히 기능이 많아지는 서비스일수록,

“말보다 Swagger 한 줄”이 더 정확하고 빠릅니다.