Saindo do inferno dos comentários do Go Swagger — criei o Swaggo

Olá,

Você já ficou estressado com os comentários do Swagger ao desenvolver APIs em Go?

Eu sempre acabava penando desse jeito:

• "O 4º argumento de // @Param era required ou description mesmo...?"
• "Cometi um erro de digitação em dto.UserRequest e só descobri em tempo de execução"
• "Ter que pesquisar toda vez o que esse comentário significa"

Por isso criei uma extensão para o VS Code chamada Swaggo.

Como funciona?

Forma antiga:

// @Param id query string true "사용자 ID"  
// @Success 200 {object} dto.UserResponse "성공"  

Você precisa decorar a ordem, e não dá para entender tudo de relance.

Jeito do Swaggo:

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

No momento em que você digita, ele converte automaticamente para os comentários padrão do Swagger.
No editor, aparece no formato de anotações com boa legibilidade, e no arquivo real é salvo como comentários padrão.

Principais recursos

✅ Nomes de parâmetros explícitos - sem precisar decorar a ordem
✅ Autocompletar da IDE - autocompleta nome da anotação, chaves e até tipos
✅ Inferência de tipos - reconhecimento automático de structs Go
✅ Conversão em tempo real - converte para comentários Swagger assim que você digita
✅ Pré-visualização no hover - confira o resultado da conversão na hora
✅ Snippets - templates para GET/POST

Exemplo de uso real

@Summary("교실 생성")  
@Description("새로운 교실을 생성합니다")  
@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")  

Por que criei isso?

Enquanto fazíamos desenvolvimento de backend em Go no time, manter a documentação Swagger era doloroso demais.

Feedbacks são bem-vindos!

Quero saber se isso realmente pode ajudar quem desenvolve APIs em Go.
Experimentem e, se encontrarem algum incômodo ou tiverem ideias de melhoria, me avisem!

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