swaggo / swag

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

v2: x-name is a tab too far for API Operation #1913

Open mtuska opened 1 month ago

mtuska commented 1 month ago

Describe the bug In the v2 branch with the --v3.1 option, the x-name parsing is placing the extended attributes within "responses" of a path, rather than inside the path object itself. Using the swagger v2 parser works as expected, with no additional indentation, but v3.1 is failing. I am correcting this locally with a quick sed on the yaml(Lazy-man's bug fix).

To Reproduce

// PostAction   godoc
// @Summary     Execute a specified action
// @Description This endpoint allows the execution of a specified action
// @ID          postAction
// @Tags        action
// @Param       action  path    string  true    "The action to be performed"
// @Success 200 {object}    Action_Result   "Successful execution of the action"
// @Router      /action/{action} [post]
// @Security    ApiKeyAuth
//
// @x-openai-isConsequential    true
func PostAction(c *gin.Context) {
}

Then with the other boiler plate, create the 3.1 spec. swag-v2 init --v3.1

The above results in the following for me:

  /action/{action}:
    post:
      description: This endpoint allows the execution of a specified action
      operationId: postAction
      parameters:
      - description: The action to be performed
        in: path
        name: action
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/action.Action_Result'
          description: Successful execution of the action
        x-openai-isConsequential: true
      security:
      - ApiKeyAuth: []
      summary: Execute a specified action on a CPE
      tags:
      - action

Expected behavior Simply expect the extended attribute to be indented 1 set less.

  /action/{action}:
    post:
      description: This endpoint allows the execution of a specified action
      operationId: postAction
      parameters:
      - description: The action to be performed
        in: path
        name: action
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/action.Action_Result'
          description: Successful execution of the action
      x-openai-isConsequential: true
      security:
      - ApiKeyAuth: []
      summary: Execute a specified action on a CPE
      tags:
      - action

Your swag version v2.0.0-rc3

Your go version go version go1.23.1 linux/amd64

Desktop (please complete the following information):

ubogdan commented 1 month ago

OAS 3 has a different code for parsing since the spec is different. Not a surprise. if you need this feature in v2 (OAS 3) please feel free to contribute.