Raus aus der Go-Swagger-Kommentarhölle – ich habe Swaggo gebaut

Hallo,

kennt ihr das auch, wenn ihr APIs in Go entwickelt und die Swagger-Kommentare euch in den Wahnsinn treiben?

Ich habe mich jedes Mal mit solchen Dingen herumgeschlagen:

• "War das 4. Argument von // @Param required oder description...?"
• "Einen Tippfehler in dto.UserRequest gemacht und erst zur Laufzeit bemerkt"
• "Jedes Mal wieder nachschauen müssen, was dieser Kommentar eigentlich bedeutet"

Deshalb habe ich eine VS-Code-Erweiterung namens Swaggo gebaut.

Wie funktioniert das?

Bisheriger Ansatz:

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

Man muss sich die Reihenfolge merken, und auf den ersten Blick ist nicht klar, was was ist.

Swaggo-Ansatz:

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

Sobald man etwas eingibt, wird es automatisch in standardisierte Swagger-Kommentare umgewandelt.
Im Editor erscheint es in einer gut lesbaren Annotationsform, in der eigentlichen Datei wird es aber als Standardkommentar gespeichert.

Hauptfunktionen

✅ Explizite Parameternamen - Reihenfolge nicht mehr auswendig lernen
✅ IDE-Autovervollständigung - Autovervollständigung für Annotationsnamen, Keys und Typen
✅ Typinferenz - Go-Structs werden automatisch erkannt
✅ Echtzeit-Konvertierung - wird direkt beim Eingeben in Swagger-Kommentare umgewandelt
✅ Hover-Vorschau - Umwandlungsergebnis sofort prüfen
✅ Snippets - Vorlagen für GET/POST

Beispiel aus der Praxis

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

Warum habe ich das gebaut?

Bei der Backend-Entwicklung mit Go im Team war die Pflege der Swagger-Dokumentation einfach zu mühsam und schmerzhaft.

Feedback willkommen!

Ich bin gespannt, ob das für Leute, die APIs mit Go entwickeln, in der Praxis wirklich hilfreich ist.
Probiert es gern aus und sagt mir Bescheid, wenn euch etwas stört oder ihr Ideen für Verbesserungen habt!

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