I want to display three possible response samples on Swagger-UI for HTTP status code 200.

Here's what I have tried so far:

1. Using multiple @Success annotations above the function.
2. Referring to the Swaggo/swag documentation and attempting to use a Markdown file with @x-codeSample.
3. Asking ChatGPT for guidance.

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/swaggo/files v1.0.1
    github/swaggo/gin-swagger v1.6.0
    github/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) {
      ...
    }

Despite these efforts, I couldn't find a working example of using an external file, and my attempts with annotations, Markdown, and raw JSON have not been successful.

Could someone provide clear instructions or an example to achieve this?

I prefer using a JSON file or Markdown file to define and present the different responses, instead of directly defining structs in the code, if possible.

I want to display three possible response samples on Swagger-UI for HTTP status code 200.

Here's what I have tried so far:

1. Using multiple @Success annotations above the function.
2. Referring to the Swaggo/swag documentation and attempting to use a Markdown file with @x-codeSample.
3. Asking ChatGPT for guidance.

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/swaggo/files v1.0.1
    github/swaggo/gin-swagger v1.6.0
    github/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) {
      ...
    }

Despite these efforts, I couldn't find a working example of using an external file, and my attempts with annotations, Markdown, and raw JSON have not been successful.

Could someone provide clear instructions or an example to achieve this?

I prefer using a JSON file or Markdown file to define and present the different responses, instead of directly defining structs in the code, if possible.

• go
• swagger-ui
• go-gin

1 Answer 1

unfortunately, it seems that is not possible in the current version of the swaggo/swag that use Swagger 2.0 (see here).

This feature already implemented in the v2 branch of that package, which will use OpenAPI 3.0 (the merged pull request).