go-swagger的简单使用

一、下载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: 响应