给golang加一个swagger[gin-swagger] golang

目录
安装gin插件
安装swag工具
安装gin-swagger
【给golang加一个swagger[gin-swagger]】导入gin-swagger
生成docs接口文档
启动项目
接口描述说明
操作前需要自主完成Go的开发环境搭建
提前准备
安装gin插件

go get -u -v github.com/gin-gonic/gin

安装swag工具

go get -u github.com/swaggo/swag/cmd/swag

执行完成后，需要将swag所在路径设置为PATH，设置方式如下（如果已经设置则跳过此步骤）
将$GOPATH/bin 加入到$PATH中：

export PATH = $PATH:$GOPATH/bin

验证是否成功：

swag -v

显示如下信息，则表示已配置成功
swag version v1.5.1

安装gin-swagger 首先需要下载两个安装包：

go get -u -v github.com/swaggo/gin-swaggergo get -u -v github.com/swaggo/gin-swagger/swaggerFiles

以上，准备工作就已经就绪，开始撸代码：
说明：
swagger的实现方式是通过在代码中通过注释的方式进行修饰，并通过swag工具自动生成接口文档
导入gin-swagger

import "github.com/swaggo/gin-swagger" // gin-swagger middleware import "github.com/swaggo/gin-swagger/swaggerFiles" // swagger embed files

gin-swagger 的示例代码如下：
代码示例：

package mainimport ( "github.com/gin-gonic/gin" "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" _ "./docs" // docs is generated by Swag CLI, you have to import it. )// @title Swagger Example API // @version 1.0 // @description This is a sample server Petstore server. // @termsOfService http://swagger.io/terms/// @contact.name API Support // @contact.url http://www.swagger.io/support // @contact.email support@swagger.io// @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html// @host petstore.swagger.io // @BasePath /v2 func main() { r := gin.New() config := &ginSwagger.Config{ URL: "http://localhost:8080/swagger/doc.json", //The url pointing to API definition } // use ginSwagger middleware to r.GET("/swagger/*any", ginSwagger.CustomWrapHandler(config, swaggerFiles.Handler)) r.Run() }

生成docs接口文档在main.go 的目录下执行 swag init 自动生成接口文档

swag init 2019/07/03 11:30:24 Generate swagger docs.... 2019/07/03 11:30:24 Generate general API Info, search dir:./ 2019/07/03 11:30:26 create docs.go atdocs/docs.go 2019/07/03 11:30:26 create swagger.json atdocs/swagger.json 2019/07/03 11:30:26 create swagger.yaml atdocs/swagger.yaml

执行完成后，在main.go 所在目录下会生成一个docs文件夹，内容如下：
main.go
docs ----------
|---docs.go
|---swagger.json
|----swagger.yaml
启动项目

go run main.go

访问： http://localhost:8080/swagger/index.html 就可以看到swagger 接口了
界面如下：

文章图片

接口描述说明可访问 https://github.com/EDDYCJY/go-gin-example 获取最新说明
// @注册用户
// @Description Register User
// @Accept multipart/form-data
// @Produce json
// @Param username formData string true "username"
// @Param password formData string true "password"
// @Success 200 {string} string "ok"
// @Router /register [post]

@param 特殊说明
对于post ， body里面提交的表单信息类型使用 formData
对于get 或 url中增加的参数类型使用 query
path 中需要使用 path 类型
@Param [Paramname] [path/query/formdata] [int/string] [true/false] [description]