I want to display three possible response samples on Swagger-UI for HTTP status code 200.
Here's what I have tried so far:
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) {
...
}
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.
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).