Sortir de l’enfer des commentaires Go Swagger — j’ai créé Swaggo

Bonjour,

Vous est-il déjà arrivé de stresser à cause des commentaires Swagger en développant une API en Go ?

Moi, je galérais à chaque fois de ce genre de manière :

• "Le 4e argument de // @Param, c’était required ou description déjà..."
• "J’ai fait une faute dans dto.UserRequest et je ne m’en rends compte qu’au runtime"
• "Je dois rechercher à chaque fois ce que signifie ce commentaire"

J’ai donc créé une extension VS Code appelée Swaggo.

Comment ça marche ?

Méthode classique :

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

Il faut mémoriser l’ordre des éléments, et on ne comprend pas immédiatement ce que chaque partie veut dire.

Méthode Swaggo :

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

Dès la saisie, le contenu est automatiquement converti en commentaires Swagger standard.
Dans l’éditeur, cela s’affiche sous forme d’annotations lisibles, et dans le fichier réel, c’est enregistré comme des commentaires standard.

Fonctionnalités principales

✅ Noms de paramètres explicites — plus besoin de mémoriser l’ordre
✅ Autocomplétion IDE — autocomplétion des noms d’annotation, des clés et même des types
✅ Inférence de types — reconnaissance automatique des structures Go
✅ Conversion en temps réel — transformation en commentaires Swagger dès la saisie
✅ Aperçu au survol — visualisation immédiate du résultat de conversion
✅ Snippets — modèles GET/POST fournis

Exemple d’utilisation réel

@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")  

Pourquoi l’avoir créé ?

Dans mon équipe, en développant le back-end en Go, la maintenance de la documentation Swagger était devenue vraiment pénible.

Vos retours sont les bienvenus !

Je me demande si cela peut réellement aider les personnes qui développent des API en Go.
Essayez-le et dites-moi s’il y a des points gênants ou des idées d’amélioration !

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