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

#go #vscode #swagger #showdev

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
}