GOPROXY=https://goproxy.cn/,direct go install github.com/zeromicro/goctl-swagger@latest
将$GOPATH/bin中的goctl-swagger添加到环境变量
-
创建api文件
info( title: "type title here" desc: "type desc here" author: "type author here" email: "type email here" version: "type version here" ) type ( RegisterReq { Username string `json:"username" validate:"min=10"` // can get parameter constraints from [validate](https://github.com/go-playground/validator) tag Password string `json:"password"` Mobile string `json:"mobile"` } LoginReq { Username string `json:"username"` Password string `json:"password"` } UserInfoReq { Id string `path:"id"` } UserInfoReply { Name string `json:"name"` Age int `json:"age"` Birthday string `json:"birthday"` Description string `json:"description"` Tag []string `json:"tag"` } UserSearchReq { KeyWord string `form:"keyWord"` } ) service user-api { @doc( summary: "注册" ) @handler register post /api/user/register (RegisterReq) @doc( summary: "登录" ) @handler login post /api/user/login (LoginReq) @doc( summary: "获取用户信息" ) @handler getUserInfo get /api/user/:id (UserInfoReq) returns (UserInfoReply) @doc( summary: "用户搜索" ) @handler searchUser get /api/user/search (UserSearchReq) returns (UserInfoReply) }
-
生成swagger.json 文件
goctl api plugin -plugin goctl-swagger="swagger -filename user.json" -api user.api -dir .
-
指定Host，basePath，schemes api-host-and-base-path
goctl api plugin -plugin goctl-swagger="swagger -filename user.json -host 127.0.0.2 -basepath /api -schemes https,wss" -api user.api -dir .
-
swagger ui 查看生成的文档
docker run --rm -p 8083:8080 -e SWAGGER_JSON=/foo/user.json -v $PWD:/foo swaggerapi/swagger-ui -
Swagger Codegen 生成客户端调用代码(go,javascript,php)
for l in go javascript php; do docker run --rm -v "$(pwd):/go-work" swaggerapi/swagger-codegen-cli generate \ -i "/go-work/rest.swagger.json" \ -l "$l" \ -o "/go-work/clients/$l" done