如何使用swagger整合api

swagger-ui的使用

首先有个swagger-ui这个项目，可以根据swagger.json文件的内容，以一种非常漂亮的页面风格显示api信息。
可以直接下载swagger-ui的项目代码，在dist目录下有已经用npm编译好的html页面，直接打开index.html就可以看到。
在地址栏里会是一个默认的值http://petstore.swagger.io/v2/swagger.json，这个值是获取的一个server下的某个路径下的swagger.json文件，所以如果你想自己编写一个swagger.json文件，也必须放在一个服务下跑，才可以正常显示api。

如何编写swagger.json

swagger.json有自己的格式，我们写代码时不可能写一个api就修改下swagger.json文件，所以需要一种自动生成swagger.json的工具。
一般是借鉴其他语言里的形式，在函数上以特殊规则编写注释，这样就可以使用工具统一生成swagger.json文件
最早注释的形式是在beego里自动集成的，后来https://github.com/yvasiyarov/swagger借鉴beego编写了一个工具，根据注释可以生成各种格式的文档，再后来vmware赞助了一个项目https://github.com/go-swagger/go-swagger，就是借鉴了yvasiyarov的思路，功能更加完善。

如何使用go-swagger

假设已经有一些编写好的go代码文件，直接在目录下执行

1	swagger generate spec -o ./swagger.json

有了swagger.json文件之后，可以放到项目里保存。如果想查看api信息，可以执行以下命令启动服务。

参照openshift项目，只保存json文件就可以。如果想在web服务的指定端口直接可以访问API文档，那另说

1	swagger serve swagger.json

默认自动启动一个OpenAPI风格的API文档

1	http://localhost:61593/docs

而此时swagger.json文件的服务器地址是

1	http://localhost:61593/swagger.json

需要把这个地址放到swagger-ui里，就可以显示swagger-ui风格的API文档

如何编写api注释

下面是一个例子，详细的可以参考goswagger的文档https://goswagger.io

// 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.