在很多框架中都会看到swagger这个词，这个组件，到底是干什么的呢?
我所了解的swagger常见功能:
1. API文档生成工具，用户对系统中的API进行说明，以及提供测试接口。
2. 代码自动生成功能(就是根据特定的格式，生成RESTful风格的代码，是不是很神奇？是不是感觉写API代码块下岗了？)
在github上查找go语言版本的swagger，发现了下班这个包
go-swagger。下载下来后，根据里边example中的代码测试了一下，神奇的发现,根据swagger.json文件，居然生成了一堆go代码。打开一看，这些代码实现了swagger.json定义好的API.。感觉如果只要会写swagger的配置文件，就不用写代码了(娱乐一下，开个玩笑)。
其实，我只是想找一个能够生成API文档的工具，顺便提供测试接口就可以了。突然给我蹦出来一个可以生成golang代码的工具，除了惊奇之外，其实依然没有满足我的需求。
继续查找，找到了swagger-ui。下载下来后，按照提示,在dist目录中运行了index.html。出现了网上介绍的界面，发现其中有一个浏览框，输入的就是swagger.json。顿时就明白了：
1. 原来swagger-ui是根据swagger.json中定义API展示出来。
2. go-swagger是根据swagger.json中定义的API，将其生成为代码。
我的需求是生成API文档，其实我需要将我的代码生成出swagger.json文件，而swagger.json中又是有一套自己的语法格式，问题就来了，要想满足我的需求，就需要有一个工具，能根据我的代码，生成swagger中语法格式的swagger.json文件。
在go-swagger中，除了能够根据swagger.json生成代码外，其实也可以根据代码，生成swagger.json文件，执行下边操作:
swagger generate spec -o ./swagger.json但是使用go-swagger生成swagger.json，需要你的代码中按照他们的格式写注释。如下几种标签:
swagger:meta
swagger:route [method] [path pattern] [?tag1 tag2 tag3] [operation id]
swagger:parameters [operationid1 operationid2]
swagger:operation [method] [path pattern] [?tag1 tag2 tag3] [operation id]
swagger:response [?response name]
swagger:model [?model name]
swagger:allOf
swagger:strfmt [name]
swagger:allOf org.example.something.TypeName
对于上述的语法介绍，请参考官方文档:go-swagger docs
下边来一段注释代码示例:
// swagger:operation GET /v1/auth/domain/get domainController getDomainInfo
//
// If the request is successful, will return domain information that the user be able to access.
//
// The system will check user permissions.
// So,you must first login system,and then you can send the request.
//
// You must pass in two arguments, first is offset ,second is limit.
//
// ---
// produces:
// - application/json
// - application/xml
// - text/xml
// - text/html
// parameters:
// - name: offset
// in: query
// description: start row number
// required: true
// type: integer
// format: int32
// - name: limit
// in: query
// description: maximum number of results to return
// required: true
// type: integer
// format: int32
// responses:
// '200':
// description: success
// '403':
// description: Insufficient permissions
// '421':
// description: get domain information failed.也就是说，只要在我们的代码中，按照go-swagger提供的语法格式编写注释，然后再使用go-swagger提供的命令，就可以生成swagger.json文件。最后在swagger-ui中打开我们的swagger.json文件，就可以在线查看我们的API文档。
swagger-ui域go-swagger的关系式，这两个工具,约定好了一个文件格式，也可以成为协议。就算没有go-swagger这个工具，你用别的工具，只要能将你的代码生成swagger.json这种语法格式的文件，就可以在swagger-ui中打开。
go-swagger的灵感来源于yvasiyarov,
而在yvasiyarov的github上,他(她)的灵感来源于beego，所以，如果想省事，直接在beego中开发API,beego内部封装了swagger工具，bee可以直接生成swagger.json文件。在swagger-ui中打开这个文件，就可以查看API文档,并进行测试。
下边来一张swagger中API界面示例:
