Dynamically generate "examples"

[manuelarte]

Hi,

Imagine that we have the following Error response when there is an error in our application

type ErrorResponse struct {
  Errors []string `json:"errors" example:"['Invalid headers']"`
  Message string `json:"message" example:"['Bad Request']"`
}

When I generate the documentation with swag, I get a "proper" example in swagger.

But now I want to reuse that ErrorResponse for different error scenarios, and I want to use a different "example"

type ErrorResponse struct {
  Errors []string `json:"errors" example:"['TCP connection failed']"`
  Message string `json:"message" example:"['Internal Server Error']"`
}

But I can't have different "examples" for the same Go struct. What I am doing right now, it's to create different structs to cover the different examples that I want to show.

So, something like this:

type ErrorResponse400Example struct {
  Errors []string `json:"errors" example:"['Invalid headers']"`
  Message string `json:"message" example:"['Bad Request']"`
}
type ErrorResponse500Example struct {
  Errors []string `json:"errors" example:"['TCP connection failed']"`
  Message string `json:"message" example:"['Internal Server Error']"`
}
...
// @Failure 400 {object} common.ErrorResponse400Example "Bad Request"
// @Failure 500 {object} common.ErrorResponse500Example "Internal Server Error, please try again later"
func (c *Controller) Update(c *gin.Context) {
...
}

But, is it possible to do it in a different way? Is it possible to dynamically generate the examples in any way?

[cardilloscreations]

This is exactly my problem. I am using Fiber with a custom handler to emit the JSON for a fiber.Error (which is just a code and message). I want to be able to reuse that struct in my definition since that's what's actually being emitted. However, if I do that, I have no way to specify the example for each @Failure using the same struct.

My "workaround" is not really correct or satisfying because it has consequences that I don't like. What I did was created a "mirror" struct that had the same definition, just to provide the different example for each.

// DO NOT USE. This is a mirror of `fiber.Error` to provide a better example in Swagger documentation.
// Ultimately, the custom `JSONErrorHandler` will emit the JSON as a `fiber.Error`.
type UnauthorizedErrorResponse struct {
	Code    int    `json:"code" example:"401"`
	Message string `json:"message" example:"Failed to get user info from JWT"`
}

// DO NOT USE. This is a mirror of `fiber.Error` to provide a better example in Swagger documentation.
// Ultimately, the custom `JSONErrorHandler` will emit the JSON as a `fiber.Error`.
type InternalServerErrorResponse struct {
	Code    int    `json:"code" example:"500"`
	Message string `json:"message" example:"Unexpected error occurred"`
}

While this solves the problem of generating the example output the way I want, this also means I'm generating new schema types when it's really the same object. Also, it makes it redundant because the code always matches the name. So if any generators create a client based on this, it will seem unnecessary, confusing, and poorly done. 🙃

What I really need is exactly what's being called for here. I need to be able to specify the response type as fiber.Error and then be able to provide an example for each @Failure declaration. I see there is a SchemaExample for @Param so maybe that solution would work here also?