给golang加一个swagger[gin-swagger]

目录

安装gin插件

安装swag工具

安装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-swagger

go 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 main

import (
	"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 [email protected]

// @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 at  docs/docs.go
2019/07/03 11:30:26 create swagger.json at  docs/swagger.json
2019/07/03 11:30:26 create swagger.yaml at  docs/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]