swaggo / swag

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

generate security AND error #1290

Open guhan121 opened 2 years ago

guhan121 commented 2 years ago

Describe the bug A clear and concise description of what the bug is.

// AttributeExample godoc
// @Summary      attribute example
// @Description  attribute
// @Tags         example
// @Accept       json
// @Produce      json
// @Param        enumstring  query     string  false  "string enums"    Enums(A, B, C)
// @Param        enumint     query     int     false  "int enums"       Enums(1, 2, 3)
// @Param        enumnumber  query     number  false  "int enums"       Enums(1.1, 1.2, 1.3)
// @Param        string      query     string  false  "string valid"    minlength(5)  maxlength(10)
// @Param        int         query     int     false  "int valid"       minimum(1)    maximum(10)
// @Param        default     query     string  false  "string default"  default(A)
// @Success      200         {string}  string  "answer"
// @Failure      400         {string}  string  "ok"
// @Failure      404         {string}  string  "ok"
// @Failure      500         {string}  string  "ok"
// @Router       /examples/attribute [get]
// @Security appId
// @Security sign
// @Security timestamp
// @Security operator
func (c *Controller) AttributeExample(ctx *gin.Context) {
    ctx.String(http.StatusOK, fmt.Sprintf("enumstring=%s enumint=%s enumnumber=%s string=%s int=%s default=%s",
        ctx.Query("enumstring"),
        ctx.Query("enumint"),
        ctx.Query("enumnumber"),
        ctx.Query("string"),
        ctx.Query("int"),
        ctx.Query("default"),
    ))
}

want generate like blow in yaml

      security:
      - appId: []
        sign: []
        timestamp: []
        operator: []

but generate this

      security:
      - appId: []
      - sign: []
      - timestamp: []
      - operator: []

企业微信截图_16602775667297

To Reproduce Steps to reproduce the behavior:

  1. Go to '...'
  2. Click on '....'
  3. Scroll down to '....'
  4. See error

Expected behavior A clear and concise description of what you expected to happen.

Screenshots If applicable, add screenshots to help explain your problem.

Your swag version e.g. 1.4.1

Your go version e.g. 1.12.0

Desktop (please complete the following information):

Additional context Add any other context about the problem here.

https://swagger.io/docs/specification/2-0/authentication/api-keys/

Ewocker commented 2 years ago

Just run into same issue.

apoorvpal01 commented 2 months ago

The docs and implementation seem to be contradictory for AND/OR operators in security tags.

https://github.com/swaggo/swag/blob/807dd1ff15b1aeb068fd41bf2f83f6352a7240a2/operation.go#L741-L768

While I believe the grouping of the AND security methods would make more sense (// @Security securityMethod1 && securitymethod2) than grouping OR, the current godoc spec would mean that ORs are present on the same line and grouped in the same map element (contradictory to what swagger yaml spec specifies).

https://swagger.io/docs/specification/2-0/authentication/#:~:text=Using%20Multiple%20Authentication%20Types

Since Swagger YAML expects the output to contain the security methods grouped with AND in the same YAML element, converting it after creating the map incorrectly would be quite tedious.

Could we switch to an && grouping in the next major release? (breaking change)

// @Security: securityMethod1[option1,option2] && securityMethod2
// @Security: securityMethod3

would translate to

security:
  - securityMethod1:
    - option1
    - option2
    securityMethod2:
  - securityMethod3: