goctl-swagger/README.md

# goctl-swagger

### 1. 编译goctl-swagger插件

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

### 2. 配置环境

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

### 3. 使用姿势

* 创建api文件

    ```go
    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 文件

    ```shell script
    goctl api plugin -plugin goctl-swagger="swagger -filename user.json" -api user.api -dir .
    ```

* -pack 开启外层响应包装并指定外层响应结构名称

    ```bash
    goctl api plugin -plugin goctl-swagger='swagger -filename user.json -pack Response' -api user.api -dir .
    ```

- 使用 -response指定相应结构

  ```bash
goctl api plugin -plugin goctl-swagger='swagger -filename user.json -pack Response -response "[{\"name\":\"trace_id\",\"type\":\"string\",\"description\":\"链路追踪id\"},{\"name\":\"code\",\"type\":\"integer\",\"description\":\"状态码\"},{\"name\":\"msg\",\"type\":\"string\",\"description\":\"消息\"},{\"name\":\"data\",\"type\":\"object\",\"description\":\"数据\",\"is_data\":true}]";' -api user.api -dir .
    ```

* 指定Host，basePath，schemes [api-host-and-base-path](https://swagger.io/docs/specification/2-0/api-host-and-base-path/)

    ```shell script
    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 查看生成的文档

    ```shell script
     docker run --rm -p 8083:8080 -e SWAGGER_JSON=/foo/user.json -v $PWD:/foo swaggerapi/swagger-ui
   ```

* Swagger Codegen 生成客户端调用代码(go,javascript,php)

  ```shell script
  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
  ```