API response wrapper usage

[sankethpb]

Describe the bug
In our project, we use a API response wrapper struct as shown below for all responses. The response contains "meta" which has status code and error message if any and a "data" section which can include another struct. I am not sure how to make swag include other structs.

//NOTE: this code is an example and may contain syntax errors
type APIResponse struct {
   Meta `json:"meta"`
   Data interface{} `json:"data"`
}

type Cars struct {
   Name  string `json:"name"`
  Model string `json:"model"`
}

type Meta struct {
     Code int `json:"code"` 
     ErrorMessage string `json:"errorMessage"`
   } 

// @Summary Get all cars
// @Description get all card
// @Tags cars
// @Produce  json
// @Success 200 {object} APIResponse
// @Router /cars [get]
app.GET("/cars", func(ctx context){
ctx.JSON(APIResponse{ Meta: Meta{200,ErrorMessage:""}, Data : Cars{"ABC","DEF"})
})

Here the actual response is APIResponse{ Meta: Meta{200,ErrorMessage:""}, Data : Cars{"ABC","DEF"}

with the annotation // @success 200 {object} APIResponse, swag generates definitions for "Meta" struct and leave "Data" as an object type without reference. This is as expected.

Is there anyway to specify that "Data" should refer "Cars" struct ? something like below?

// @Success 200 {object} APIResponse{ Data: Cars} 

Your swag version
1.4.1

Your go version
1.12.1

Desktop (please complete the following information):

• OS: Windows 10

[ubogdan]

As far as i understand from your data modeling @success can be an error too ? If not what is the purpose of Meta in APIResponse.
// @success 200 {object} APIResponse{ Data: Cars}

[sankethpb]

No, this structure is common for every response.

[ubogdan]

Unfortunately it's not possible to define a response this way.

// @Success 200 {object} APIResponse{ Data: Cars} 

The most simple way is to define a response for each endpoint

type CarsResponse struct {
   Meta `json:"meta"`
   Data Cars `json:"data"`
}
// @success 200 {object} CarsResponse

[xibolun]

No, this structure is common for every response.

My Common Response like yours

type CommonResponse struct {
	Status  string `json:"status"`
	Message string `json:"message"`
	Content interface{} `json:"content"`
}

My response struct like this:

// DictResponse 字典返回
type DictResponse struct {
	// 主键
	ID     int    `json:"id" example:"1"`
	Type   string `json:"type" validate:"required,gt=0,lt=16" comment:"字典类型"`
	Name   string `json:"name" validate:"required,gt=0,lt=16" comment:"字典名称"`
	Value  string `json:"value" validate:"required,gt=0,lt=64" comment:"value"`
	Remark string `json:"remark" comment:"备注"`
}

My Solution is:

Define a struct base CommonResponse and DictResponse in another package "api"

// SwaggerDictResponse
type SwaggerDictResponse struct {
	Status  string           `json:"status"`
	Message string           `json:"message"`
	Content val.DictResponse `json:"content"`
}

then change the route comment

// @Success 200 {object} api.SwaggerDictResponse
// @Router /dict [post]

[sdghchj]

Reference #651.