swaggo / swag

Automatically generate RESTful API documentation with Swagger 2.0 for Go.
MIT License
10.24k stars 1.17k forks source link

field of `any` type behaves badly when specifying `json` field name #1833

Open shomeax opened 1 month ago

shomeax commented 1 month ago

Describe the bug swag fails to generate proper OpenAPI definition when field of any type is used simultaneously with json hint.

To Reproduce Steps to reproduce the behavior:

for the following example structure:

type MyRequest struct {
    Name            string                   `json:"name" binding:"required,validName,max=200" example:"Bob"` // Name
    Value             any                    `json:"value" binding:"omitempty" example:"dunno"`      // Arbitrary value
}

type MyResponse struct {
    Id    string     `json:"id" example:"2ef01247-936d-4855-a3e4-6d5b024fcf7d"` // Object id
}

and following handler:

// @Summary Create Object
// @Tags Version v1.0.0
// @Produce json
// @Accept  json
// @Success 202 {object} MyResponse
// @Param  data body MyRequest true "New object parameters"
// @Router /v1/objects [POST]
// @description  Create object is async operation, it means that server returns 202 Accepted and continue work asynchronously.
func (handler *ObjectsHttpHandler) NewObject(context *gin.Context) {
...
}

Following swagger document is generated when I use swag init --parseDependency:

definitions:
  MyRequest:
    type: object
  MyResponse:
    properties:
      id:
        description: Object id
        example: 2ef01247-936d-4855-a3e4-6d5b024fcf7d
        type: string
    type: object
...
paths:
  /v1/objects:
    get:
      ...
    post:
      consumes:
      - application/json
      description: |-
        Create object is async operation, it means that server returns 202 Accepted and continue work asynchronously.
      parameters:
      - description: New object parameters
        in: body
        name: data
        required: true
        schema:
          $ref: '#/definitions/MyRequest'
      produces:
      - application/json
      responses:
        "202":
          description: Accepted
          schema:
            $ref: '#/definitions/MyResponse'
...

Otherwise speaking, the whole MyRequest object is squashed into blob without properties, bug.

Expected behavior However, if I remove the json: "value" ... hint, e.g. for the following structure:

type MyRequest struct {
    Name            string                   `json:"name" binding:"required,validName,max=200" example:"Bob"` // Name
    Value             any                       // Arbitrary value
}

The result document is generated properly:

definitions:
  MyRequest:
    properties:
      name:
        description: Name of object
        example: Bob
        maxLength: 200
        type: string
      value:
        description: Arbitrary object
    required:
    - name
    type: object
  MyResponse:
    properties:
       ...
...

Your swag version v1.16.3

Your go version 1.19.2

sdghchj commented 3 weeks ago

Maybe there is no suitable example for type any.