gin-swagger api生成项目实践

Golang gin-swagger api生成项目实践

一、gin-swagger简介

在现代Web开发中，构建清晰、规范的API文档至关重要，它可以帮助开发者更好地理解接口，并提高协作效率。Gin-Swagger是一个优秀的Go语言库，专门为基于Gin框架的微服务提供了方便的Swagger集成方案。通过简洁的注解方式，你可以轻松地生成符合OpenAPI规范的API文档。

---

• 项目：

  • Gin-Swagger是Swaggo的一部分，它将Swagger集成到Gin框架中，使得编写和维护RESTful API文档变得更加简单。该项目实现了自动代码注解解析，可以自动生成一个交互式的Swagger UI界面，供开发者测试和查看API。

• 特点：

  • 基于Swagger: Gin-Swagger遵循OpenAPI v3标准，这是Swagger的最新版本，广泛用于描述Web服务接口。
  • 易于集成: 只需在Gin路由定义上添加简单的注解，就能让Gin-Swagger自动发现并生成API文档。这意味着你的文档将与代码同步更新，减少了手动维护的成本。
  • 智能代码解析: 库会扫描源代码中的注释，提取参数、返回值、错误码等信息，生成详细的API描述。
  • 交互式文档: 提供了内置的Swagger UI，开发者可以直接在界面上进行接口调用和测试，提高了开发和调试的效率。

二、gin-swagger 请求参数使用

• query参数

  query参数： query 用于将请求参数放在 URL 中传递。它将请求参数作为键值对，用 “?” 符号分隔，放在 URL 的查询字符串中。例如，GET 请求中通过 query 传递参数的方法如下：

  GET /some/path?param1=value1&param2=value2 HTTP/1.1
  

  其中**?param1=value1&param2=value2** 就是 query，它将请求参数传递给服务器。

  type QRequest struct {
  	Username string `form:"username"`  // 用户名
  	Nickname string `form:"nickname"`  // 昵称
  }
  
  type QResponse struct {
  	Code int         `json:"code"`
  	Msg  string      `json:"msg"`
  	Data interface{} `json:"data,omitempty"`
  }
  
  // @Summary QueryTest
  // @Schemes
  // @Tags API.QueryTest
  // @Produce json
  // @Accept application/x-www-form-urlencoded
  // @Param username query string true "用户名"
  // @Param nickname query string true "昵称"
  // @Success 200 {object} QResponse
  // @Router /api/query-test [post]
  func QueryTest(c *gin.Context) {
  	req := new(QRequest)
      // 也可以通过 c.Parma("username") 获取
      if err := c.ShouldBindForm(req); err != nil {
         c.JSON(http.StatusInternalServerError, QResponse{
  			Code: code,
  			Msg:  msg,
  			Data: "requect parmas is error.",
  		}
  		return
  	}
      c.JSON(http.StatusOK, QResponse{
  		Code: code,
  		Msg:  msg,
  		Data: req,
  	}
  }
  

• params参数

  params参数： params 用于将请求参数放在请求体中传递。它将请求参数封装成键值对，用逗号分隔，放在请求体(body)的 JSON 或 XML 格式中。例如，POST 请求中通过 params 传递参数的方法如下：

  POST /some/path HTTP/1.1
  Content-Type: application/json
  {
  "param1": "value1",
  "param2": "value2"
  }
  

  其中，请求体中的 JSON 格式包含了请求参数，它将请求参数传递给服务器。

  type QRequest struct {
  	Username string `form:"username"`  // 用户名
  	Nickname string `form:"nickname"`  // 昵称
  }
  
  type QResponse struct {
  	Code int         `json:"code"`
  	Msg  string      `json:"msg"`
  	Data interface{} `json:"data,omitempty"`
  }
  // @Summary ParamsTest
  // @Schemes
  // @Tags API.Params
  // @Produce json
  // @Accept application/json
  // @Param Params body QRequest true "Params请求参数"
  // @Success 200 {object} QResponse
  // @Router /api/params-test [post]
  func ParamsTest(c *gin.Context) {
  	req := new(QRequest)
      if err := c.ShouldBindJSON(req); err != nil {
         c.JSON(http.StatusInternalServerError, QResponse{
  			Code: code,
  			Msg:  msg,
  			Data: "requect parmas is error.",
  		}
  		return
  	}
      c.JSON(http.StatusOK, QResponse{
  		Code: code,
  		Msg:  msg,
  		Data: req,
  	}
  }
  

• form-data参数

  form-data参数: form参数用于前端通过表单形式向后端发起请求。它将数据通过表单形式封装传输，本质上是params参数的一种。

  type QRequest struct {
  	id string `form:"id"`  // 查询id
  }
  
  type QResponse struct {
  	Code int         `json:"code"`
  	Msg  string      `json:"msg"`
  	Data interface{} `json:"data,omitempty"`
  }
  // @Summary FormDataTest
  // @Schemes
  // @Tags API.FormData
  // @Produce json
  // @Accept application/x-www-form-urlencoded
  // @Param id formData string true "查询id"
  // @Success 200 {object} QResponse
  // @Router /api/formdata-test [post]
  func FormDataTest(c *gin.Context) {
  	req := new(QRequest)
      if err := c.ShouldBindForm(req); err != nil {
         c.JSON(http.StatusInternalServerError, QResponse{
  			Code: code,
  			Msg:  msg,
  			Data: "requect parmas is error.",
  		}
  		return
  	}
      c.JSON(http.StatusOK, QResponse{
  		Code: code,
  		Msg:  msg,
  		Data: req,
  	}
  }
  

三、gin-swagger 响应参数使用

• @Success

  # 格式 @Success 200 {数据类型：string/int/object} 对应的数据结构 string/int/xxx结构体名；例如：
  // @Success 200 {object} response.Response
  

• @Failure

  # 格式 @Success 异常状态码 {数据类型：string/int/object} 对应的数据结构 string/int/xxx结构体名；例如：
  // @Failure 400 {object} code.Failure
  // @Failure 500 {object} code.Error
  

四、gin-swagger + gin初始化

1. Gin初始化

   func main(){
       gin.SetMode(gin.ReleaseMode)
   	if debug {
   		gin.SetMode(gin.DebugMode)
   	}
   	r := gin.Default()
   
   	r.HandleMethodNotAllowed = true
       
       r.Run(":8000")
   }
   

2. Swagger相关开发依赖安装

    go get -u github.com/swaggo/swag
    go get -u github.com/swaggo/files
    go get -u github.com/swaggo/gin-swagger
   # 需要下载最新的swag客户端程序用于生成docs文档，推荐直接github下载
   https://github.com/swaggo/swag/releases
   

3. Swagger+Gin

   package main
   
   import (
   	"github.com/gin-gonic/gin"
   	khttp "github.com/go-kratos/kratos/v2/transport/http"
   	swaggerfiles "github.com/swaggo/files"
   	ginSwagger "github.com/swaggo/gin-swagger"
   	"swag-demo/app/docs" // 此为swagger文档目录，在第5步讲解怎么生成
   )
   
   func main(){
       gin.SetMode(gin.ReleaseMode)
   	if debug {
   		gin.SetMode(gin.DebugMode)
   	}
   	r := gin.Default()
   
   	r.HandleMethodNotAllowed = true
       
       // 在没有执行swag init前（也就是第5步）， 下面docs.xxx注释掉或者先不写
       docs.SwaggerInfo.BasePath = "/api/v1"
   	docs.SwaggerInfo.Title = "管理后台接口"
   	docs.SwaggerInfo.Description = "实现一个管理系统的后端API服务"
   	docs.SwaggerInfo.Version = "1.0"
   	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
       
       rg := r.Group("/api/v1")
   	go app.RegisterRoute(rg)
       
       r.Run(":8000")
   }
   

五、api开发示例

• 直接使用上面的案例-Params参数

package app


type QRequest struct {
	Username string `form:"username"`  // 用户名
	Nickname string `form:"nickname"`  // 昵称
}

type QResponse struct {
	Code int         `json:"code"`
	Msg  string      `json:"msg"`
	Data interface{} `json:"data,omitempty"`
}
// @Summary ParamsTest
// @Schemes
// @Tags API.Params
// @Produce json
// @Accept application/json
// @Param Params body QRequest true "Params请求参数"
// @Success 200 {object} QResponse
// @Router /params-test [post]
func ParamsTest(c *gin.Context) {
	req := new(QRequest)
    if err := c.ShouldBindJSON(req); err != nil {
       c.JSON(http.StatusInternalServerError, QResponse{
			Code: code,
			Msg:  msg,
			Data: "requect parmas is error.",
		}
		return
	}
    c.JSON(http.StatusOK, QResponse{
		Code: code,
		Msg:  msg,
		Data: req,
	}
}
           
func RegisterRoute(router *gin.RouterGroup) {
	//	注册
	router.POST("/params-test", ParamsTest)
}           

六、docs生成及项目启动

1、找到下载的swag程序，复制到项目根路径（其他也可以）
2、执行init命令，例如windows环境：
   # .\swag.exe init -g main主函数入口路径
   .\swag.exe init -g .\app\x-ids\cmd\cmd.go
3、将生成的docs(在当前执行目录)移动到合适的地方，例如本项目：
   swag-demo/app/docs 位置，并在swagger初试化的地方引入对应包，初始化swagger相关基础信息
4、go build 
5、访问 http://127.0.0.1:8000/swagger/index.html # 即可看淡到swagger主页

七 、yapi + swagger docs构建yapi管理

1、部署yapi服务：https://github.com/fjc0k/docker-YApi
2、导入gin-swagger项目生成的swagger文档
3、调试使用：https://hellosean1025.github.io/yapi/documents/index.html