go - How to display multiple HTTP 200 Response Samples on Swagger-UI using Swaggoswag

admin管理员组
文章数量:1023554

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

Here's what I have tried so far:

Using multiple @Success annotations above the function.
Referring to the Swaggo/swag documentation and attempting to use a Markdown file with @x-codeSample.
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:

Using multiple @Success annotations above the function.
Referring to the Swaggo/swag documentation and attempting to use a Markdown file with @x-codeSample.
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.

Share Improve this question asked Nov 19, 2024 at 2:10 陳禮佑 234 bronze badges

Add a comment |

1 Answer 1

Sorted by: Reset to default 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).

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

Here's what I have tried so far:

Using multiple @Success annotations above the function.
Referring to the Swaggo/swag documentation and attempting to use a Markdown file with @x-codeSample.
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:

Using multiple @Success annotations above the function.
Referring to the Swaggo/swag documentation and attempting to use a Markdown file with @x-codeSample.
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.

Share Improve this question asked Nov 19, 2024 at 2:10 陳禮佑 234 bronze badges

Add a comment |

1 Answer 1

Sorted by: Reset to default 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).

本文标签： goHow to display multiple HTTP 200 Response Samples on SwaggerUI using SwaggoswagStack Overflow

版权声明：本文标题：go - How to display multiple HTTP 200 Response Samples on Swagger-UI using Swaggoswag - Stack Overflow 内容由热心网友自发贡献，该文观点仅代表作者本人，转载请联系作者并注明出处：http://it.en369.cn/questions/1745586142a2157605.html，本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容，一经查实，本站将立刻删除。

369IT编程

go - How to display multiple HTTP 200 Response Samples on Swagger-UI using Swaggoswag - Stack Overflow

1 Answer 1

1 Answer 1

更多相关文章