goctl-swagger

goctl-swagger

从 https://github.com/zeromicro/goctl-swagger FORK，但原项目有 bug 且不好修，干脆直接重构一版，目前只支持 swagger v2，预计未来 支持v3，并支持更灵活的参数

1. 编译goctl-swagger插件

GOPROXY=https://goproxy.cn/,direct go install github.com/henryjhenry/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中使用
      goctl api plugin -plugin goctl-swagger="swagger -target swagger.json" -api user.api -dir .
  
      # 在本地使用
      go run main.go swagger -target swagger.json 0<~/tmp.json
  

  tmp.json:

  {
      "ApiFilePath": "your.api",
      "Dir": "."
  }
  

• 指定Host，basePath，schemes api-host-and-base-path

  goctl api plugin -plugin goctl-swagger="swagger -target 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
  

4. run test

cd goctl-swagger
export GOCTL_API_PATH=/your/api/path
export SWAGGER_OUTSIDE_SCHEMA=/your/outside_schema/path
go test ./render --count=1 -v

运行完毕后，会生成 swagger.json。

暂未实现对生成文件的校验。