一、下载go-swagger
go-swagger 官方下载
根据不同个的操作系统选择对应的
二、添加环境变量
2.1 window
swagger_windows_amd64.exe
将swagger_windows_amd64.exe 重命名 成 swagger.exe
然后将该软件放到D:\bin 中
然后再操作系统的PATH 中添加 D:\bin
2.2 linux
swagger_linux_amd64
重命名成 swagger
然后 将 软件放入/usr/bin 目录下
mv swagger /usr/bin/
三、go-swagger 使用
- 进入自己项目的根目录
swagger 会自己寻找main 包的
- 执行命令
swagger generate spec -o ./swagger.json // 根据swagger规范 创建 swagger.json 规范文档
swagger serve -F=swagger swagger.json // 启动一个http 服务同时将json文档放入http://petstore.swagger.io 执行
四、关于swagger-UI 的页面
如果你想要 petstore.swagger.io 的那种页面 ,你可以自己下载 https://github.com/swagger-api/swagger-ui ,
下载好后进入dist 页面执行运行index.html 即可
五、go-swagger 规范
// swagger:operation POST /api/v1/addr/del addr del
// ---
// summary: 删除用户地址
// description: 用于删除指定的用户地址
// parameters:
// - name: token
// in: body
// description: token
// type: string
// required: true
// - name: id
// in: body
// description: 地址id
// type: string
// required: true
// responses:
// 200: repoResp
// 400: badReq
你可以将上面的规范放在go源码中每个controller 函数 前面
解释
// swagger:operaion [POST:请求方式(可以是GET\PUT\DELETE...)] [url:请求地址] [标签] [用于此端点的请求] (你可以将最后两个理解为id 节点,用于标注地址)
// --- 这个部分下面是YAML格式的swagger规范.确保您的缩进是一致的和正确的
// summary: 标题
// description: 描述
// parametres: 下面是参数了
// - name: 参数名
in: [header|body|query] 参数的位置
description: 描述
type: 类型
required: 是否必须
// responses: 响应
如果喜欢看小说,请到183小说网