go-zero 框架下 swagger 使用

安装swagger

https://github.com/go-swagger/go-swagger/releases

我的运行环境是 centos7 x64， 因此下载swagger_linux_amd64

生成 swagger json 文件

bookstore.api

type (
        addReq {
                Book  string `form:"book"`
                Price int64  `form:"price"`
        }

        addResp {
                Ok bool `json:"ok"`
        }
)

type (
        checkReq {
                Book string `form:"book"`
        }

        checkResp {
                Found bool  `json:"found"`
                Price int64 `json:"price"`
        }
)

service bookstore-api {
        @handler AddHandler
        get /add (addReq) returns (addResp)

        @handler CheckHandler
        get /check (checkReq) returns (checkResp)
}

生成swagger.json 文件

goctl api plugin -plugin goctl-swagger="swagger -filename bookstore.json" -api bookstore.api -dir .

指定Host，basePath api-host-and-base-path， 注意这里的ip,port 是 go-zero开发服务所监听的 ip,port

goctl api plugin -plugin goctl-swagger="swagger -filename bookstore.json -host 192.168.99.196:8088 -basepath /" -api bookstore.api -dir .

通过swagger将api文档以web形式展示，并测试接口

./swagger_linux_amd64  serve -F=swagger  bookstore.json   --port 9088 --host 0.0.0.0  --no-open

注意， --port， – host 参数是定访问doc的ip和端口
–no-open则不会自动打开浏览器（没有安装 X 环境的系统，就需要加上该参数）
详细配置可以通过 ./swagger_linux_amd64 serve --help 查看

查看 api文档， 并测试接口
http://192.168.99.196:9088/docs

注意：

swagger 测试页面， 可能会报错接口调用失败， 这是CORS(跨域) 的问题，需要在server端设置相应的header 属性， 如下， 是通过 go-zero的中间件， 设置response 的 Access-Control-Allow-Origin
详细的， 可参考 关于跨域自定义header的问题

server.Use(func(next http.HandlerFunc) http.HandlerFunc {
        return func(w http.ResponseWriter, r *http.Request) {
            w.Header().Set("Access-Control-Allow-Origin", "*")
            next(w, r)
        }
    })