Go语言-整合gin-swagger生成API文档

Posted 2021-07-06 阿拉的梦想

Go语言-整合gin-swagger生成API文档

• swagger介绍
• 第一步，添加注释
• • 注解解释
• 第二步，使用swag命令生成文档
• 第三步，引入gin-swagger渲染文档数据
• 测试
• 其他示例
• • post接口配置

swagger介绍

Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用，以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档，代码生成和测试用例生成。

这里以gin框架为例，使用gin-swagger库以使用Swagger 2.0自动生成RESTful API文档
想要使用gin-swagger为你的代码自动生成接口文档，一般需要下面三个步骤：

1. 按照swagger要求给接口代码添加声明式注释，具体参照【声明式注释格式】。
2. 使用swag工具扫描代码自动生成API接口文档数据
3. 使用gin-swagger渲染在线接口文档页面

第一步，添加注释

因为go不支持注解，所以swagger的注解添加在注释中，然后被swagger程序解析，要用swag init手动生成代码。
路由必须配置 r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))

package main

import (
	_ "demo2/docs" // 千万不要忘了导入把你上一步生成的docs
	"fmt"
	"github.com/gin-gonic/gin"
	gs "github.com/swaggo/gin-swagger"
	//"github.com/swaggo/gin-swagger/swaggerFiles"
	"github.com/swaggo/files"
	"net/http"
)
// @title 我的swagger
// @version 1.0
// @description 这里写描述信息
// @host localhost:8080
// @BasePath /
func main() {

	//生成gin引擎
	r := gin.Default()
	//初始化路由配置
	initRoutes(r)
	if err := r.Run(); err != nil {
		panic(err)
	}
}

//初始化路由配置
func initRoutes(r *gin.Engine) {
	// 访问/version的返回值会随配置文件的变化而变化
	r.GET("/version", version)
	r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
	r.GET("/user/search",userSearch)
}

//控制器方法version
// @Summary 我的接口
// @Description 这是一个version接口
// @Tags version相关接口
// @Router /version [get]
// @Produce json
// @Success 200 {string} string
func version(c *gin.Context) {

	fmt.Println("进入version方法")
	//响应
	c.String(http.StatusOK, "1.1.0")
}

//控制器方法version
// @Tags 用户相关接口
// @Summary 查询用户信息
// @Description 这是一个查询用户信息接口
// @Router /user/search [get]
// @Param username query string true "用户姓名"
// @Param address query string  false "地址"
// @Produce json
// @Success 200 {string} string
func userSearch(c *gin.Context) {
	username := c.DefaultQuery("username", "小王子")
	//username := c.Query("username")
	address := c.Query("address")
	//输出json结果给调用方
	c.JSON(http.StatusOK, gin.H{
		"message":  "ok",
		"username": username,
		"address":  address,
	})

}

注解解释

• @Title 这个 API 所表达的含义，是一个文本，空格之后的内容全部解析为 title

• @Description 这个 API 详细的描述，是一个文本，空格之后的内容全部解析为 Description

• @Param 参数，表示需要传递到服务器端的参数，有五列参数，使用空格或者 tab 分割，五个分别表示的含义如下
  1.参数名
  2.参数类型，可以有的值是 formData、query、path、body、header，formData 表示是 post 请求的数据，query 表示带在 url 之后的参数，path 表示请求路径上得参数，例如上面例子里面的 key，body 表示是一个 raw 数据请求，header 表示带在 header 信息中得参数。
  3.参数类型 string int 等
  4.是否必须 true false
  5.说明

• @Produce 响应的mime type
  使用右侧缩写即可，如json

  Mime Type	annotation
  pplication/json	application/json, json
  ext/xml	text/xml, xml
  ext/plain	text/plain, plain
  tml	text/html, html
  ultipart/form-data	multipart/form-data, mpfd
  pplication/x-www-form-urlencoded	application/x-www-form-urlencoded, x-www-form-urlencoded
  pplication/vnd.api+json	application/vnd.api+json, json-api
  pplication/x-json-stream	application/x-json-stream, json-stream
  pplication/octet-stream	application/octet-stream, octet-stream
  mage/png	image/png, png
  mage/jpeg	image/jpeg, jpeg
  mage/gif	image/gif, gif

• @Success
  如： @Success 200 {string} string
  成功返回给客户端的信息，三个参数，第一个是 status code。第二个参数是返回的类型，必须使用 {} 包含，第三个是返回的对象或者字符串信息，如果是 {object} 类型，那么 bee 工具在生成 docs 的时候会扫描对应的对象，这里填写的是想对你项目的目录名和对象，例如 models.ZDTProduct.ProductList 就表示 /models/ZDTProduct 目录下的 ProductList 对象。
  三个参数必须通过空格分隔

• @Failure
  失败返回的信息，包含两个参数，使用空格分隔，第一个表示 status code，第二个表示错误信息

• @router
  如： @Router /user/search [get]
  路由信息，包含两个参数，使用空格分隔，第一个是请求的路由地址，支持正则和自定义路由，和之前的路由规则一样，第二个参数是支持的请求方法,放在 [] 之中，如果有多个方法，那么使用 , 分隔。

第二步，使用swag命令生成文档

编写完注释后，使用以下命令安装swag工具：

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

在项目根目录执行以下命令，使用swag工具生成接口文档数据。每次接口注释更改后，都要用它来更新文档：

	swag init

执行完上述命令后，如果你写的注释格式没问题，此时你的项目根目录下会多出一个docs文件夹：

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

第三步，引入gin-swagger渲染文档数据

在main.go 或其他用到的地方引入依赖包demo2/docs

import (
	_ "demo2/docs" // 千万不要忘了导入把你上一步生成的docs
	...
)

测试

将工程启动起来,日志如下：

[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.

[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /version                  --> main.version (3 handlers)
[GIN-debug] GET    /swagger/*any             --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (3 handlers)
[GIN-debug] GET    /user/search              --> main.userSearch (3 handlers)
[GIN-debug] Environment variable PORT is undefined. Using port :8080 by default
[GIN-debug] Listening and serving HTTP on :8080

访问http://localhost:8080/swagger/index.html

调用接口：

其他示例

post接口配置

//接口路由配置
r.POST("/user/search_post",userSearchPost)

// @Tags 用户相关接口
// @Summary 查询用户信息-post
// @Description 这是一个查询用户信息接口
// @Router /user/search_post [post]
// @Param username formData string true "用户姓名"
// @Param address formData string  false "地址"
// @Success 200 {string} string
func userSearchPost(c *gin.Context) {
	username := c.PostForm("username")
	//username := c.Query("username")
	address := c.DefaultPostForm("address","默认地址")
	//输出json结果给调用方
	c.JSON(http.StatusOK, gin.H{
		"message":  "ok",
		"username": username,
		"address":  address,
	})
}