README.md

goctl-swagger

1. 编译goctl-swagger插件

GOPROXY=https://goproxy.cn/,direct go install github.com/zeromicro/goctl-swagger@latest

2. 配置环境

将$GOPATH/bin中的goctl-swagger添加到环境变量

3. 使用姿势

• 创建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"`
    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 api-host-and-base-path

  goctl api plugin -plugin goctl-swagger="swagger -filename user.json -host 127.0.0.2 -basepath /api" -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