swaggo 주석 순서를 외우는 게 지겨워서 이걸 만들었습니다

Source: Dev.to

Introduction

Swaggo는 Go API 문서화를 위해 훌륭하지만, 어노테이션에 필요한 인수 순서가 번거로울 수 있습니다. 다음과 같이 작성할 때마다:

// @Param id query string true "User ID"

정확한 순서인 name, in, type, required, description을 기억해야 합니다. 이 때문에 실수가 잦아지고, 오타가 발생하며, 팀 Slack에서 “순서가 뭐였지?” 라는 질문이 자주 오게 됩니다.

The Problem with Positional Arguments

• Memory load – 각 인수의 위치를 외워야 합니다.
• Common mix‑ups – type과 required 플래그가 종종 뒤바뀝니다.
• Silent errors – 구조체 이름(dto.UserReponse 등)의 오타가 런타임까지 잡히지 않습니다.
• Onboarding friction – 새로운 개발자는 API 로직에 집중하기보다 순서를 배우는 데 시간을 씁니다.

Solution: Named‑Parameter Annotations

VS Code 확장 프로그램을 사용하면 Swaggo 어노테이션을 이름이 지정된 파라미터 형태로 작성할 수 있습니다:

@Param(name="id", in="query", type=string, required=true, desc="User ID")
@Success(code=200, schema=dto.UserResponse, desc="Success")

이 확장은 실시간으로 이를 일반 Swaggo 주석으로 변환하므로, 소스 파일에는 여전히 표준 // @Param 구문이 남아 있지만, 더 읽기 쉬운 이름이 지정된 파라미터 버전을 편집하게 됩니다.

How It Works

• No order memorization – 키(name, in, type, required, desc)를 원하는 순서대로 지정합니다.
• IDE assistance – 어노테이션 이름과 Go 타입에 대한 자동 완성, 그리고 생성된 주석을 보여주는 툴팁 제공.
• Snippets – 흔히 사용하는 패턴을 빠르게 삽입.
• Live conversion – 입력하는 즉시 확장이 기본 주석을 업데이트합니다.

Example

Named‑parameter version (what you edit)

@Summary("Create classroom")
@Tags("classroom", "admin")
@Param(name="body", in="body", type=dto.CreateClassroomRequest, required=true, desc="Classroom creation request")
@Success(code=200, schema=dto.ClassroomResponse, desc="Success")
@Router("/classrooms", "post")
func CreateClassroom(c echo.Context) error {
    // your code
}

Generated Swaggo comment (what ends up in the file)

// @Summary Create classroom
// @Tags classroom,admin
// @Param body body dto.CreateClassroomRequest true "Classroom creation request"
// @Success 200 {object} dto.ClassroomResponse "Success"
// @Router /classrooms [post]
func CreateClassroom(c echo.Context) error {
    // your code
}

첫 번째 블록만 편집하면 되고, 확장이 변환을 담당합니다.

Benefits

• Reduced syntax questions – 새로운 팀원이 인수 순서에 대해 묻는 일이 줄어듭니다.
• Fewer mistakes – 형식이 잘못된 어노테이션 때문에 코드 리뷰에서 발생하는 잡음이 감소합니다.
• Better IDE support – 자동 완성과 타입 검증으로 오류를 조기에 잡을 수 있습니다.
• Easier refactoring – IDE가 어노테이션에 사용된 Go 타입을 검증할 수 있어 리팩터링이 쉬워집니다.

Installation

VS Code Marketplace에서 “Swaggo”를 검색하거나 직접 설치합니다:

• Marketplace link:
• GitHub repository:

Limitations

• 이 확장은 편집기 측면에서만 편리함을 제공하며, 참조된 타입이 실제로 존재하는지는 검증하지 않습니다. 해당 검증은 여전히 Swaggo CLI가 수행합니다.
• 현재는 VS Code 전용이며, 다른 에디터는 향후 수요가 있으면 지원될 수 있습니다.

Conclusion

이름이 지정된 파라미터 어노테이션을 사용하면 Swaggo의 위치 기반 인수 순서를 외울 필요가 없어져, Go에서 Swagger 문서를 더 빠르고 명확하게, 오류를 최소화하면서 작성할 수 있습니다. 이 확장은 무료이며 기존 Swaggo 도구와 호환되고, 코드와 100 % 호환됩니다.

GitHub에 이슈를 열어 개선 사항이나 제안을 남겨 주세요. 즐거운 문서화 되세요!