[Q&A] How to give examples to objects in line

[xorima]

Describe the bug In the documentation it says I can give detail to the generated examples in the below maner, but when I try this I get an error:

Readme example:

Model composition in response

// JSONResult's data field will be overridden by the specific type proto.Order
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"

type JSONResult struct {
    Code    int          json:"code" 
    Message string       json:"message"
    Data    interface{}  json:"data"
}

error got on my code : 2024/10/06 12:45:03 ParseComment error in file /Users/jfield/dev/xorima/github-bridge/internal/app/webhook.go :invalid type: Response{status=200,message=

To Reproduce Code: file: app/webhook.go

package app

import (
    "github.com/xorima/slogger"
    "log/slog"
    "net/http"
)

type WebhookHandler struct {
    log *slog.Logger
}

func NewWebhookHandler(log *slog.Logger) *WebhookHandler {
    return &WebhookHandler{
        log: log.With(slog.String("handler", "webhook")),
    }
}

// Post - Receives the GitHub webhooks
//
//  @Summary        This API is there to receive the GitHub events.
//  @Description    Once received, this will add them to the event stream for consumers.
//  @Tags           Webhooks
//  @Accept         json
//  @Produce        json
//  @Success        200 {object} Response{status=200,message="Success"} "Successful Response"
//  @Failure            401 {object} Response{status=401,message="Unauthorized"}    "Unauthorized"
//  @Failure          404   {object} Response{status=404,message="Not Found"}       "Failure Response"
//  @Router         /api/v1/webhook/github [post]
func (wh *WebhookHandler) Post(w http.ResponseWriter, r *http.Request) {
    wh.log.Info("got request")
    resp := NewResponse(http.StatusAccepted, "Accepted")
    w.WriteHeader(resp.Status)
    _, err := w.Write(resp.ToJson())
    if err != nil {
        wh.log.Error("failure in writing webhook response", slogger.ErrorAttr(err))
    }
}

func (wh *WebhookHandler) RegisterRoutes(r Router) {
    r.Post("/v1/webhook/github", wh.Post)
}

file: app/response.go

package app

import "encoding/json"

type Response struct {
    Status  int    `json:"status"`
    Message string `json:"message"`
}

func NewResponse(status int, message string) *Response {
    return &Response{Status: status, Message: message}
}

func (r *Response) ToJson() []byte {
    // the error here is impossible due to well known object.
    resp, _ := json.Marshal(r)
    return resp
}

Expected behavior swag init generates with appropriate examples

Screenshots

Your swag version 1.16.3

Your go version e.g. 1.12.0

Additional context I am doing this so I will not have to create multiple structs that are identical but have different examples, as that would add complexity which is not desired

[martinyonatann]

based on attachment readme. the code should be like this

type Response struct {
    Status int `json:"status"`
    Data   any `json:"data"`
}

type DTOs struct {
    A string `json:"a" example:"a"`
    B string `json:"b" example:"b"`
    C string `json:"b" example:"c"`
}

// Post - Receives the GitHub webhooks
//
//  @Summary        This API is there to receive the GitHub events.
//  @Description    Once received, this will add them to the event stream for consumers.
//  @Tags           Webhooks
//  @Accept         json
//  @Produce        json
//  @Success        200 {object} Response{data=DTOs}    "Successful Response"
//  @Router         /api/v1/webhook/github [post]
func (wh *WebhookHandler) Post(w http.ResponseWriter, r *http.Request) {
    wh.log.Info("got request")
    resp := NewResponse(http.StatusAccepted, "Accepted")
    w.WriteHeader(resp.Status)
    _, err := w.Write(resp.ToJson())
    if err != nil {
        wh.log.Error("failure in writing webhook response", slogger.ErrorAttr(err))
    }
}

[xorima]

Thanks @martinyonatann

using the example has gotten closer, but still not fully there

this is using this as the example:

type Response struct {
    Status  int    `json:"status"`
    Message string `json:"message"`
}

type Success struct {
    A int `json:"status" example:"200"`
}

//  @Success        202 {object} Response{status=Success}   "Successful Response"

It feels like I will have to make a custom response type for each, which while not end of the world it's not what I originally intended :)