wI2L / fizz

:lemon: Gin wrapper with OpenAPI 3 spec generation
https://pkg.go.dev/github.com/wI2L/fizz
MIT License
214 stars 52 forks source link

A way to override default example #110

Open HermanPierre opened 8 months ago

HermanPierre commented 8 months ago

Hello, I am currently writing my API swagger doc so for example on this route:

router.GET("/tl/:id", []fizz.OperationOption{
        fizz.ID("get_by_id"),
        fizz.Description("Get by its id."),
        fizz.Response("200",
            "Example of a successful call by id.<br>",
            dedicated.TlResponse{}, nil, GetByIdSuccessExemple),
    }, tonic.Handler(handler.GetById, http.StatusOK))

But if do that I get an error because examples for status 200 are already generated by tonic, so I've added example tags to my response struct:

image image

but some fields of my struct are type interface{} because I can't know the exact type of object I'm getting from my API. So if I use the example tag on an interface{} type, in my swaggers the example for this field says "string"

image

But it's not clear for someone who reads this and don't know the project, so I tried using the fizz.Response on another status and I can put some object example values in those interface{} fields... I could use "default" status code but I think its still not clear in the swagger to have status 200 example with "string" for a field and under it, having an object for the same field :/

Is their a way to override the 200 status/default example ? Thanks :)