Gin 如何动态生成模型 swagger 文档

在做 API 接口开发时, 一般会统一 API 返回格式, 例如

{
“code”: 200,
“data”: {
//xxxxx
//xxxxx
},
“message”: “OK”
}
在后端代码定义中, 也会定义一个结构体来对应这种结构, 并且, 由于 data 字段里的数据是未知的(与具体业务相关), 所以会定义一个 interface 来接收

type ApiResponse struct {
Code int json:"code"
Msg string json:"message"
Data interface{} json:"data"
}
然后根据具体业务响应, 向 data 传入不同的模型, 比如

c.JSON(200, ApiResponse{200, “OK”, User})
但是这里有个很大的问题, swagger 文档中, 这个接口的返回值该怎么定义?

// @Summary 获取用户信息
// …
// …
// @Success 200 {object} ApiResponse “ok”
func GetUser(c *gin.Context) {
xxxx
}
如果这样定义, 生成的文档会是下面这样, 因为原始 ApiResponse 就是一个 interface, 所以是空

但是这样的文档写出来就没什么意义了, 大多数的做法就是会专门定义一个用于 swagger 显示的结构体, 类似这样

type UserResponse struct {
Code int json:"code"
Msg string json:"message"
Data User json:"data"
}
虽然效果有了, 但是这样无疑增加了巨多的工作量, 让写代码变得索然无味, 翻看 swaggo/swag 的文档, 发现支持了替换字段的方式, 可以完美解决现在这种问题, 效果如下

下面是测试代码

package main

import (
“net/http”
“strconv”

"github.com/gin-gonic/gin"

)

// @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()
r.GET("/user/:id", GetUser)
}

// @Summary 获取用户信息
// @Description get User by ID
// @ID get-user-by-id
// @Accept json
// @Produce json
// @Param id path int true “用户 id”
// @Success 200 {object} ApiResponse{data=User} “ok”
// @Router /user/{id} [get]
func GetUser(c *gin.Context) {
resp := new(ApiResponse)

paramID := c.Param("id")
uid, _ := strconv.Atoi(paramID)
user := User{
	ID:   uid,
	Name: "张三",
}
resp.Code = 200
resp.Msg = "OK"
resp.Data = user
c.JSON(http.StatusOK, resp)

}

type User struct {
ID int json:"id"
Name string json:"name"
}

type ApiResponse struct {
Code int json:"code"
Msg string json:"message"
Data interface{} json:"data"
}
亚马逊测评 www.yisuping.cn