Thoát khỏi địa ngục chú thích Go Swagger - Tôi đã tạo ra Swaggo

Xin chào,

Bạn đã bao giờ bị stress vì chú thích Swagger khi phát triển API bằng Go chưa?

Tôi đã nhiều lần vật lộn kiểu này:

• "Đối số thứ 4 của // @Param là required hay description nhỉ..."
• "Gõ sai dto.UserRequest mà đến lúc runtime mới phát hiện"
• "Lại phải đi tìm xem chú thích này có nghĩa là gì"

Vì thế tôi đã tạo ra một extension VS Code tên là Swaggo.

Nó hoạt động như thế nào?

Cách cũ:

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

Bạn phải nhớ thứ tự và cũng khó nắm bắt ngay được từng phần có ý nghĩa gì.

Cách của Swaggo:

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

Ngay khi bạn nhập, nó sẽ tự động chuyển đổi thành chú thích Swagger tiêu chuẩn.
Trong editor, nó hiển thị dưới dạng annotation dễ đọc hơn, còn trong file thực tế thì vẫn được lưu dưới dạng chú thích tiêu chuẩn.

Tính năng chính

✅ Tên tham số tường minh - Không cần nhớ thứ tự
✅ IDE tự động hoàn thành - Tự động hoàn thành cả tên annotation, key và type
✅ Suy luận kiểu - Tự động nhận diện struct Go
✅ Chuyển đổi thời gian thực - Vừa nhập là chuyển ngay thành chú thích Swagger
✅ Xem trước khi hover - Xem ngay kết quả chuyển đổi
✅ Snippet - Cung cấp template GET/POST

Ví dụ sử dụng thực tế

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

Tại sao tôi làm nó?

Khi làm backend bằng Go trong team, việc bảo trì tài liệu Swagger quá đau khổ.

Rất mong nhận được phản hồi!

Tôi muốn biết liệu nó có thực sự hữu ích với những người phát triển API bằng Go hay không.
Hãy dùng thử và cho tôi biết nếu có điểm nào bất tiện hoặc có ý tưởng cải thiện nhé!

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