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

WonJeong Kim — Fri, 09 Jan 2026 22:42:27 +0000

So I've been using swaggo for documenting Go APIs and honestly it works great, but...

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

Every single time I write this I have to stop and think "wait which one comes first again?"

And I know I'm not the only one because our team slack has like 10 messages asking "what's the order for @param again?"

What annoyed me

The main thing is you have to memorize the position of every argument. Like this:

// @Param id query string true "description"
//        ┬   ┬     ┬      ┬    ┬
//        name in  type  required description

And honestly I still mix up type and required sometimes.

Also when you typo a struct name:

// @Success 200 {object} dto.UserReponse "OK"

The swag CLI doesn't catch it until runtime. Super annoying.

Plus onboarding new devs is always the same conversation - "just remember the order is name, in, type, required, description" and they're like "ok but which order though"

So I made an extension

Basically you can write it like this instead:

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

It converts to normal swaggo comments as you type. So the file still has the regular // @Param stuff but in the editor you see and edit the named parameter version.

The nice thing is you don't have to remember any order. Just type the keys you want.

Here's what it looks like in practice:

@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
}

This becomes:

// @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
}

But you only edit the first version.

What it does

Named parameters so you don't have to remember order
IDE autocomplete for annotation names and your Go types
Hover over it to see what the actual swaggo comment looks like
Has snippets for common patterns
Converts in real-time as you type

Basically makes it way easier to write and read swagger docs.

Demo

You can see it converting as you type and the hover shows you the result.

Why I made this

We have like 20+ API endpoints on our team and maintaining the swagger docs was getting annoying. After using this for a few months:

New team members stopped asking about syntax
Less mistakes in code reviews
Easier to refactor because IDE can actually help validate the types

It's not perfect but it's been useful for us.

What's supported

Pretty much all the common swaggo tags - Summary, Description, Tags, Param, Success, Failure, Router, etc.

You can use named parameters for most of them or just use the old positional style if you want.

Installing

Just search "Swaggo" in VS Code extensions and install it.

Or get it from the marketplace: https://marketplace.visualstudio.com/items?itemName=narubrown.swaggo

Limitations

It doesn't actually check if the types exist in your code - that's still swag CLI's job. This just makes writing the comments easier.

Also it's VS Code only right now. Maybe I'll make it for other editors later if people want it.

Try it

It's free.

GitHub: https://github.com/NARUBROWN/swaggo

Would be cool to hear if this is actually useful or if I'm just weird for being annoyed by positional arguments lol

If you have ideas for improvements feel free to open an issue.

PS: This doesn't change Go at all, it's just editor sugar that outputs regular swaggo comments. Your code stays 100% compatible with everything.

DEV Community: WonJeong Kim