如何使用 Swaggo/swag 在 Swagger-UI 上显示多个 HTTP 200 响应示例

Question

我想在 Swagger-UI 上显示 HTTP 状态代码 200 的三个可能的响应示例。

这是我迄今为止尝试过的：

1. 在函数上方使用多个@Success注释。
2. 参考 Swaggo/swag 文档并尝试使用 @x-codeSample 的 Markdown 文件。
3. 向 ChatGPT 寻求指导。

File struct
├─api
│  └─backend
│      ├─controller
|      |     |─controller //func is declare here 
|      |
│      ├─middleware
│      └─router
├─cmd
│  └─api
|     |──main.go
|
├─docs
|  |─docs.go
|  |─swagger.json
|  |─swagger.yaml
|  |─Get signature records.md
...

# go.mod
    github.com/swaggo/files v1.0.1
    github.com/swaggo/gin-swagger v1.6.0
    github.com/swaggo/swag v1.16.3

# CLI command to generate swagger file
    swag init -g cmd/api/main.go -o ./docs

# Response model of API

    package model

    type GetDeliverySignatureResp struct {
        SignatureTypeId    int       `json:"signatureTypeId"`
            ...
    }
    type GetDeliverySignatureRespQrcode struct {
        SignatureTypeId    int       `json:"signatureTypeId"  example:"1"`
            ...
    }
    type GetDeliverySignatureRespManual struct {
        SignatureTypeId    int       `json:"signatureTypeId"  example:"2"`
            ...
    }
    type GetDeliverySignatureRespNoContact struct {
        SignatureTypeId    int       `json:"signatureTypeId"  example:"3"`
            ...
    }

# gin handler function

    package controller

    // ApiGetSignatureRecords
    // @Summary Get signature records
    // @Description 1.QrCode, 2.Manual, 3.NoContact
    // @Tags Fleet
    // @Param deliveryId path string true "deliveryId"
    // @Param Token header string true "JWT"
    // @Success 200 {object} model.GetDeliverySignatureRespQrcode "QR Code"
    // @Success 200 {object} model.GetDeliverySignatureRespManual "Manual"
    // @Success 200 {object} model.GetDeliverySignatureRespNoContact "No Contact"
    // @Router /api/{deliveryId} [GET]
    func (f *fleetController) ApiGetSignatureRecords(c *gin.Context) {
      ...
    }

尽管做出了这些努力，我还是找不到使用外部文件的工作示例，并且我对注释、Markdown 和原始 JSON 的尝试也没有成功。

有人可以提供明确的说明或示例来实现这一目标吗？

如果可能的话，我更喜欢使用 JSON 文件或 Markdown 文件来定义和呈现不同的响应，而不是直接在代码中定义结构。

Answer 1

不幸的是，在使用

swaggo/swag

的当前版本的

Swagger 2.0

中似乎不可能（参见此处）。

此功能已在该包的

v2

分支中实现，该分支将使用

OpenAPI 3.0

（合并的拉取请求）。