Swaggo - GoSwagger Genie for VS code.

GoSwagger Genie for VS Code. @Tag(...) 또는 #Tag(...) 형태의 가상 어노테이션을 입력하면, 자동으로 Go Swagger 주석(// @Tag ...)으로 변환합니다. 에디터에서는 Swagger 주석을 다시 가상 어노테이션 형태로 렌더링해 읽기 쉽고 수정하기 쉽습니다. Enter virtual annotations like @Tag(...) or #Tag(...) and they are converted into Go Swagger comments (// @Tag ...). In the editor, Swagger comments are rendered back as virtual annotations so they are easy to read and edit.

⚠️ 주의: 이 도구는 Go에 어노테이션을 도입하지 않습니다. 표준 swaggo 주석으로 변환되는 에디터 친화적인 입력 문법만을 제공합니다. Note: This tool does not introduce annotations to Go itself. It only provides editor-friendly input syntax that converts to standard swaggo comments.

목차 / Table of Contents

• 소개 / Introduction
• 주요 기능 / Key Features
• 사용 방법 / Usage
• 지원하는 어노테이션 문법 / Supported Annotation Syntax
• 어노테이션 파싱 규칙 / Parsing Rules
• 진단(Diagnostics) / Diagnostics
• 스니펫 / Snippets
• 개발 / Development
• 비고 / Notes

소개 / Introduction

기존의 // @Param ... 주석은 인자 순서를 기억해야 하고, 값이 무엇을 의미하는지 매번 해석해야 했습니다. swaggo는 @어노테이션(키=값) 문법을 제공해 의미를 명확히 하고, IDE의 타입 추론과 자동완성으로 구조체/스키마를 빠르게 작성할 수 있게 합니다. 또한 마우스 호버로 변환된 Swagger 주석을 확인할 수 있어 결과를 즉시 검증할 수 있습니다. Traditional // @Param ... comments require you to remember argument order and interpret each value every time. swaggo provides @annotation(key=value) syntax to make intent explicit, and leverages IDE type inference and autocompletion so you can write structures/schemas faster. You can also hover to preview the converted Swagger comments and verify results immediately.

주요 기능 / Key Features

• 주석 렌더링: // @Tag ... 주석을 가상 어노테이션 형태로 표시. (Render comments as virtual annotations)
• 명시적 문법: @어노테이션(키=값)으로 어떤 값인지 한눈에 파악. (Explicit syntax with @annotation(key=value))
• IDE 친화성: @어노테이션 이름 자동완성, @어노테이션(키) 자동완성, 타입 추론 지원. (IDE-friendly autocompletion and type inference)
• 가상 어노테이션 수정: 가상 @어노테이션을 직접 수정할 수 있음 (Edit virtual annotations directly)
• 즉시 변환: 입력 즉시 // @Tag ... 형식으로 변환. (Instant conversion to // @Tag ...)
• 호버 미리보기: 마우스를 올리면 변환된 Swagger 주석을 확인. (Hover preview of converted comments)
• 기본 패턴 진단: package.Type 또는 package.Function 형태를 정규식으로 검사. (Basic pattern diagnostics)
• 스니펫 제공: 자주 쓰는 GET/POST 템플릿. (GET/POST snippets)

사용 방법 / Usage

1) 입력 예시 / Input Example

@Summary("클래스 생성")
@Description("클래스 생성 API")
@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")

2) 변환 결과 / Converted Output

// @Summary 클래스 생성
// @Description 클래스 생성 API
// @Tags classroom,admin
// @Accept json
// @Produce json
// @Param body body dto.CreateClassroomRequest true "클래스 생성 요청"
// @Success 200 {object} dto.ClassroomResponse "클래스 생성 성공"
// @Failure 400 {object} echo.HTTPError "잘못된 요청"
// @Router /classrooms [post]

지원하는 어노테이션 문법 / Supported Annotation Syntax

아래는 현재 지원하는 가상 어노테이션 태그와 기본 변환 규칙입니다. Below are the supported virtual annotation tags and their default conversion rules.

기본 텍스트 계열 / Basic Text

• @Summary("텍스트") → // @Summary 텍스트
• @Description("텍스트") → // @Description 텍스트
• @ID("operationId") → // @ID operationId
• @Tags("tag1", "tag2") → // @Tags tag1,tag2
• @Accept("json", "xml") → // @Accept json xml
• @Produce("json") → // @Produce json
• @Schemes("http", "https") → // @Schemes http https
• @Security("ApiKeyAuth") → // @Security ApiKeyAuth
• @Deprecated() → // @Deprecated

Param

형식 / Format:

@Param("name", "in", type, required, "description")

변환 / Conversion:

// @Param name in type required "description"

예시 / Example:

@Param("id", "query", string, true, "사용자 ID")

// @Param id query string true "사용자 ID"

키=값 형태도 지원합니다 (순서 무관): Key=value form is also supported (order-independent):

@Param(name="id", in="query", type=string, required=true, desc="사용자 ID")

Success / Failure

형식 / Format:

@Success(code, schema, "description")
@Failure(code, schema, "description")

변환 / Conversion:

// @Success code {object} schema "description"
// @Failure code {object} schema "description"

본문 타입을 직접 지정할 수도 있습니다. You can also specify the body type explicitly.

@Success(200, "array", dto.User, "OK")

// @Success 200 {array} dto.User "OK"

지원하는 본문 타입: object, array, string, number, integer, boolean Supported body types: object, array, string, number, integer, boolean

키=값 형태 / Key=value:

@Success(code=200, schema=dto.User, desc="OK")
@Success(code=200, type=array, schema=dto.User, desc="OK")

Header

형식 / Format:

@Header(code, type, "name", "description")

변환 / Conversion:

// @Header code {type} name "description"

예시 / Example:

@Header(200, string, "Location", "redirect url")

// @Header 200 {string} Location "redirect url"

키=값 형태 / Key=value:

@Header(code=200, type=string, name="Location", desc="redirect url")

Router

형식 / Format:

@Router("/path", "method")

변환 / Conversion:

// @Router /path [method]

예시 / Example:

@Router("/classrooms", "post")

// @Router /classrooms [post]

키=값 형태 / Key=value:

@Router(path="/classrooms", method="post")

어노테이션 파싱 규칙 / Parsing Rules

• @Tag(...) 또는 #Tag(...) 모두 지원합니다. (Supports both)
• 문자열은 큰따옴표로 감싸는 것을 권장합니다. (Recommend double quotes for strings)
• 콤마로 인자를 구분합니다. (Comma-separated arguments)
• true/false, 숫자, 문자열이 혼합되어도 처리합니다. (Mixed booleans, numbers, strings)
• Summary, Description, ID, Param, Success/Failure, Header, Router는 key=value 형식도 지원합니다. (키는 대소문자 무시) (Key names are case-insensitive)
• description/desc 모두 인식하며 렌더링은 desc로 표시됩니다. (Both accepted; rendered as desc)

진단(Diagnostics) / Diagnostics

• package.Type 또는 package.Function 형태를 기본 정규식으로 검사합니다. (Regex checks for these forms)
• 형식이 맞지 않으면 해당 위치에 경고가 표시됩니다. (Warnings on invalid format)
• 실제 Go 코드에 해당 타입이 존재하는지는 검사하지 않습니다. (Does not verify types exist in code)

스니펫 / Snippets

• swagpost: POST용 가상 어노테이션 블록 (POST annotation block)
• swagget: GET용 가상 어노테이션 블록 (GET annotation block)

개발 / Development

1. 의존성 설치: npm install (Install dependencies)
2. 빌드: npm run compile (Build)
3. 실행: VS Code에서 F5로 Extension Development Host 실행 (Run via Extension Development Host)

비고 / Notes

• 현재는 입력 즉시 변환됩니다. (Instant conversion as you type)
• 필요 시 태그별 포맷 규칙을 추가로 확장할 수 있습니다. (Rules can be extended per tag)
• Swagger 주석 렌더링은 에디터에서만 보이며 파일 내용은 변경되지 않습니다. (Rendering is editor-only; file contents are unchanged)