go-swagger使用

安装

新版的go-swagger使用了谷歌的几个包，必须用代理，先说下代理。

windows，设置环境变量。GOPROXY。

阿里云的goproxy: 
http://mirrors.aliyun.com/goproxy/

 

然后下载go-swagger包，

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

安装go-swagger，移动到下载的go-swagger包目录（应该是GOPATH/src/pkg/github.com/go-swagger,理解这个意思就好，路径不一定对）。

go install ./cmd/swagger

一、生成文档文件

swagger generate spec -o ./swagger.json

解释：generate生成，spec指规格的意思 -o，这个字母o的意思是：-output即输出 。

总的命令意思就是：swagger 生成 规格 -输出 输出的路径和文件。

遇到的一个问题：

在根目录下生成的是无内容的，在main下会生成有报错内容的，在docs/下是只有doc.go的内容。 

好像是：

>set GOPATH=%CD%;%GOPATH%

将当前目录放进GOPATH，之后再main.go目录时就是正常的了。也不知道到底是为什么……

比较有意思的是，生成文档时最好在/doc/的目录下使用命令行。如果是在入口目录（/cmd/），或者根目录，生成的yml(json)会缺少info，导致启动swagger client服务失败。

二、启动服务器浏览文档

swagger serve login.yml

这里没什么说的，serve 就是启动服务的意思，后面加swagger源文件（比如之前swagger generate spec -o ./swagger.json生成的文件）。还可以设置端口号,比如：

swagger serve -p 8888 swagger.yaml

主要讲文档规则，这里遇到的坑最多。一共有：meta,route,params,operation,response,model,allOf,strfmt,discriminated,ignore。

第一个meta元数据

我是新建了一个doc目录，在下面新建doc.go。在里面写的meta元数据。这样分的清楚一些，不然很乱，真的很乱。

先说一句，如果没有看《swagger从入门到精通》，根本不知道swagger:meta的书写规则。比如前三段，第一段对应title,第二段和第三段对应description。

第二个route路径

swagger:route [method] [path pattern] [?tag1 tag2 tag3] [operation id]

搞不懂，只是标签（tag）为什么会在最显眼的位置？搞的我这个英语盲老是会错意，以为tag是接口的名称。还有后面的操作id，好像没看到有什么用。

// swagger:route GET /login/bindStudent bind existStudent
	//
	// 通过学号和姓名确定一个学生，然后将手机号更新进这个学生的字段，即绑定手机号。
	//
	// 当学生信息正确，更新cellphone字段，信息错误返回学号或姓名错误。手机号已做了格式验证。
	//
	//
	//     Consumes:
	//     - application/json
	//
	//     Produces:
	//     - application/json
	//
	//     Schemes: http, https
	//
	//     Security:
	//       api_key:
	//       oauth: read, write
	//

一个很简单的route，consumes,接收的数据类型，produces返回的数据类型，schemes,接收的通信协议方案。security安全，比如认证。

一个正常的接口，我们需要写三个swagger注释。接口路径,route ,接口参数，parameters，接口返回，response。

 

最后，还有一个比较好用的命令，检查生成的文档的错误：

swagger validate swagger.yaml