goctl plugin to parse api definitions and generate api files with handler comments retained.
go install github.com/wqyjh/[email protected]See full example at https://github.com/WqyJh/zero-template.
Inspired by zeromicro/go-zero#2464.
Define swagger document for handler in .api files.
@server(
group: user
prefix: /api/v1/user
jwt: JwtAuth
)
service api {
// UserSelf godoc
// @Summary 查询用户信息
// @Description 查询用户信息
// @Tags user
// @Security ApiKeyAuth
// @Accept json
// @Produce json
// @Param client header string true "当前设备类型: android/ios"
// @Success 200 {object} types.DataResponse{data=types.UserSelfReply}
// @Router /api/v1/user/self [get]
@handler UserSelf
get /self (UserSelfReq) returns (UserSelfReply)
}Generate api using goctl api plugin.
goctl api plugin -plugin goctl-gogen="--home ${CWD}/../template" -api def/main.api -dir ./ -style goZeroThe document defined would be rendered on handler. And if you update the api file, and regenerate the handler, handler will also be updated.
// UserSelf godoc
// @Summary 查询用户信息
// @Description 查询用户信息
// @Tags user
// @Security ApiKeyAuth
// @Accept json
// @Produce json
// @Param client header string true "当前设备类型: android/ios"
// @Success 200 {object} types.DataResponse{data=types.UserSelfReply}
// @Router /api/v1/user/self [get]
func UserSelfHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
var req types.UserSelfReq
if err := httpz.Parse(r, &req); err != nil {
httpz.ErrorLog(r.Context(), w, err)
return
}
logc.Infow(r.Context(), "UserSelfHandler", logc.Field("req", &req))
l := user.NewUserSelfLogic(r.Context(), svcCtx)
resp, err := l.UserSelf(&req)
if err != nil {
httpz.Error(w, err)
logc.Infow(r.Context(), "UserSelfHandler error", logc.Field("error", err))
} else {
httpz.OkJson(w, resp)
logc.Infow(r.Context(), "UserSelfHandler success", logc.Field("resp", resp))
}
}
}Then you can generate swagger document by swaggo.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent