给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 接口了

界面如下:

给golang加一个swagger[gin-swagger]_第1张图片

接口描述说明

可访问 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] 

 

 

 

 

 

 

 

你可能感兴趣的:(golang)