介绍

goctl-swagger插件,根据api文件定义的@doc,生成相应的swagger文档。

使用

编译goctl-swagger插件

GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/zeromicro/goctl-swagger

配置环境

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

创建api文件

info(
    title: "用户文档"
    desc: "用户接口"
    author: ""
    email: ""
    version: "1.0"
)

type (
    Pager {
        Page int `json:"page"`
        PageSize int `json:"page_size"`
    }

    UserSearchReq {
        Pager
        KeyWord string `form:"keyWord"`
    }

    UserInfoReply {
        Name string `json:"name"`
        Age int `json:"age"`
        Birthday string `json:"birthday"`
        Description string `json:"description"`
        Tag []string `json:"tag"`
    }
)

service user-api {
    @doc(
        summary: "用户搜索"
    )
    @handler searchUser
    get /api/user/search (UserSearchReq) returns (UserInfoReply)
}

执行goctl-swagger,生成文档

goctl api plugin -p goctl-swagger="swagger -filename user.json" --api user.api --dir .

文档效果

问题

当请求参数是一个匿名结构体时,解析的效果为invalid。

解决

思路一: 将解析的类型为invalid,并且匿名结构体已被定义时,将匿名结构体参数用已定义的结构体字段来进行替换。

效果如下图: