# go-swagger安装及使用
go-swagger介绍
go-swagger 为社区带来了一套完整的,功能齐全的高性能API组件,可与Swagger API一起使用:服务器,客户端和数据模型。
- 根据标准规范生成服务器
- 从摇摇欲坠的规范生成客户端
- 支持jsonschema和swagger提供的大多数功能,包括多态
- 从带注释的go代码中生成标准规范
- 配合规范使用的其他工具
- 强大的定制功能,带有供应商扩展和可定制的模板
- 我们在代码生成方面的重点是生成惯用的,快速执行的代码,该代码可与golint,go vet等配合使用
# 1 代码下载
go get github.com/go-swagger/go-swagger
1
# 2 安装swagger
安装go-swagger,移动到下载的go-swagger包目录(应该是GOPATH/src/pkg/github.com/go-swagger,理解这个意思就好,路径不一定对)。
go install ./cmd/swagger
1
# 3 swagger规范
将下面规范放在go源码中每个
controller
函数前面
// swagger:operation POST /user/addUser user addUser
// ---
// summary: 新增用户信息
// description: 用于系统用户的新增
// parameters:
// - name: username
// in: body
// description: 用户名
// type: string
// required: true
// - name: password
// in: body
// description: 密码
// type: string
// required: true
// responses:
// 200: repoResp
// 400: badReq
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 4 swagger规范解释说明
// swagger:operaion [POST:请求方式(可以是GET\PUT\DELETE...)] [url:请求地址] [标签] [用于此端点的请求] (你可以将最后两个理解为id 节点,用于标注地址)
// --- 这个部分下面是YAML格式的swagger规范.确保您的缩进是一致的和正确的
// summary: 标题
// description: 描述
// parametres: 下面是参数了
// - name: 参数名
in: [header|body|query] 参数的位置
description: 描述
type: 类型
required: 是否必须
// responses: 响应
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
# 5 生成swagger.json
进入自己项目的根目录,根据swagger规范,创建
swagger.json
规范文档
swagger generate spec -o ./swagger.json
1
- 解释:generate生成,spec指规格的意思 -o,这个字母o的意思是:-output即输出 。
- 总的命令意思就是:swagger 生成 规格 -输出 输出的路径和文件。
# 6 启动swagger服务
启动一个http
服务同时将json
文档放入http://petstore.swagger.io 执行
swagger serve -F=swagger D:\go_project\src\kratos\docs\api.swagger.json
1
# 7 关于swagger-UI的页面
如果你想要
petstore.swagger.io
的那种页面,你可以自己下载https://github.com/swagger-api/swagger-ui , 下载好后进入dist
页面执行运行index.html
即可
← go-redis文档 Golang定时任务 →