goctl-swagger的使用方法

最新推荐文章于 2024-03-13 11:02:55 发布

small_777

最新推荐文章于 2024-03-13 11:02:55 发布

阅读量963

点赞数

文章标签： golang 文档资料

本文链接：https://blog.csdn.net/weixin_49369316/article/details/129439722

版权

goctl-swagge的使用方法

官网对goctl-swagger的使用介绍是这样的，但是很不完善，很不清楚，我第一次用搞了两小时才ok

官网描述

下面我对自己使用过程中的问题和步骤都详细讲解

一、下载goctl-swagger插件

直接敲下面的两个命令就可以下载了

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

二、配置环境

1.将$GOPATH/bin中的goctl-swagger添加到环境变量
打开你的 $GOPATH/bin 目录，看到的是：（里面有goctl-swagger.exe文件）
在这里插入图片描述
2.然后配置环境变量，就是将这个文件的路径添加到系统的path中：

三、创建api文件

这里就是业务的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 ./api/edgeinstance/manage.json -host localhost:8888" -api ./api/edgeinstance/manage.api -dir .

-filename 后面的参数是你要生成的swagger文件的地址和名称；
-host 后面的参数是你要调用接口的地址和端口；
-basepath是基路径，没啥用，一般不写；
-api 后面的参数是你定义的api文件的地址；
-dir 是生成的目录，一般都是.

五、swagger ui 查看生成的文档

docker run -p 8087:8080 -e SWAGGER_JSON=/edgemanage/manage.json -v C:\Users\wangzhirong\GolandProjects\src\ut-iot\api-server\api\edgeinstance:/edgemanage swaggerapi/swagger-ui