Show GN: Go Swagger 주석 지옥에서 벗어나기 - Swaggo 만들었습니다
(marketplace.visualstudio.com)안녕하세요,
Go로 API 개발하다가 Swagger 주석 때문에 스트레스 받으신 적 있으신가요?
저는 매번 이런 식으로 삽질했습니다:
- "// @Param의 4번째 인자가 required였나 description이었나..."
- "dto.UserRequest 오타 냈는데 런타임에서야 발견"
- "이 주석이 뭘 의미하는지 매번 검색해보기"
그래서 Swaggo라는 VS Code 확장을 만들었습니다.
어떻게 동작하나요?
기존 방식:
// @Param id query string true "사용자 ID"
// @Success 200 {object} dto.UserResponse "성공"
순서 외워야 하고, 뭐가 뭔지 한눈에 안 들어옵니다.
Swaggo 방식:
@Param(name="id", in="query", type=string, required=true, desc="사용자 ID")
@Success(code=200, schema=dto.UserResponse, desc="성공")
입력하는 순간 자동으로 표준 Swagger 주석으로 변환됩니다.
에디터에서는 가독성 좋은 어노테이션 형태로 보이고, 실제 파일에는 표준 주석으로 저장됩니다.
주요 기능
✅ 명시적 파라미터 이름 - 순서 외울 필요 없음
✅ IDE 자동완성 - 어노테이션 이름, 키, 타입까지 자동완성
✅ 타입 추론 - Go 구조체 자동 인식
✅ 실시간 변환 - 입력 즉시 Swagger 주석으로 변환
✅ 호버 미리보기 - 변환 결과 즉시 확인
✅ 스니펫 - GET/POST 템플릿 제공
실제 사용 예시
@Summary("교실 생성")
@Description("새로운 교실을 생성합니다")
@Tags("classroom", "admin")
@Accept("json")
@Produce("json")
@Param(name="body", in="body", type=dto.CreateClassroomRequest, required=true, desc="교실 생성 요청")
@Success(code=200, schema=dto.ClassroomResponse, desc="교실 생성 성공")
@Failure(code=400, schema=echo.HTTPError, desc="잘못된 요청")
@Router("/classrooms", "post")
왜 만들었나요?
팀에서 Go로 백엔드 개발을 하다보니 Swagger 문서 유지보수가 너무 고통스러웠습니다.
피드백 환영합니다!
Go로 API 개발하시는 분들께 실제로 도움이 될지 궁금합니다.
사용해보시고 불편한 점이나 개선 아이디어 있으면 알려주세요!