I got tired of memorizing swaggo comment order, so I made this

Published: 1 week ago (January 9, 2026 at 05:42 PM EST)

3 min read

Source: Dev.to

Introduction

Swaggo is great for documenting Go APIs, but the required order of arguments in its annotations can be a hassle. Every time you write something like:

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

you have to remember the exact sequence: name, in, type, required, description. This leads to frequent mistakes, typos, and a lot of “what’s the order again?” messages on team Slack.

The Problem with Positional Arguments

Memory load – You must memorize the position of each argument.
Common mix‑ups – Type and required flags are often swapped.
Silent errors – Typos in struct names (e.g., dto.UserReponse) aren’t caught until runtime.
Onboarding friction – New developers spend time learning the order instead of focusing on the API logic.

Solution: Named‑Parameter Annotations

A VS Code extension lets you write Swaggo annotations using named parameters:

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

The extension converts these to the regular Swaggo comments in real time, so the source file still contains the standard // @Param syntax, but you edit the more readable named‑parameter version.

How It Works

No order memorization – You specify keys (name, in, type, required, desc) in any order.
IDE assistance – Autocomplete for annotation names and Go types, plus hover tooltips showing the generated comment.
Snippets – Quick insertion of common patterns.
Live conversion – As you type, the extension updates the underlying comment.

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
}

You only edit the first block; the extension handles the conversion.

Benefits

Reduced syntax questions – New team members stop asking about argument order.
Fewer mistakes – Less noise in code reviews from malformed annotations.
Better IDE support – Autocomplete and type validation help catch errors early.
Easier refactoring – IDE can validate Go types referenced in the annotations.

Installation

Search for “Swaggo” in the VS Code Marketplace or install directly:

Marketplace link:
GitHub repository:

Limitations

The extension only provides editor‑side sugar; it does not validate that referenced types actually exist. That validation is still performed by the Swaggo CLI.
Currently supports VS Code only. Other editors may get support in the future if there’s demand.

Conclusion

Named‑parameter annotations eliminate the need to memorize Swaggo’s positional argument order, making Swagger documentation in Go faster, clearer, and less error‑prone. The extension is free, works with existing Swaggo tooling, and leaves your code 100 % compatible.

Feel free to open issues on GitHub for improvements or suggestions. Happy documenting!