swaggo / swag

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

APIKey pair does not work as specified in the swagger specification #1447

Open aosti opened 1 year ago

aosti commented 1 year ago

Describe the bug I've tried to implement the pair of api key as described in https://swagger.io/docs/specification/2-0/authentication/api-keys/, section "Pair of API Keys". But it doesn't seem to work.

To Reproduce I've specified in the main:

// @securitydefinitions.apikey AccessKeyId // @in header // @name access-key-id // @securitydefinitions.apikey AccessKeySecret // @in header // @name access-key-secret

Then, in the api handler I've added: // @Security AccessKeyId // @Security AccessKeySecret

I was expecting this to generate an AND condition, but the final swagger.yaml generates: security:

Which is interpreted as an OR, not an AND. I've tried this because of the issue #977.

Expected behavior Expected an AND condition requiring key id and key secret.

Your swag version v1.8.9

Your go version go1.19.2 darwin/amd64

Desktop (please complete the following information):

komron-m commented 1 year ago

I faced the same issue, but problem is in typo in annotations, i.e. securitydefinitions => securityDefinitions

...
// @securityDefinitions.apikey  AccessKeyId
// @in                          header
// @name                        access-key-id
// @securityDefinitions.apikey  XApiKey
// @in                          header
// @name                        x-api-key
// @description                 Description for what is this security definition being used.
...

Then, in handlers add:
// @Security AccessKeyId
// @Security AccessKeySecret
soonio commented 1 year ago

version: 2.0-rc3

bad: (use swag fmt, cant work)

//  @securityDefinitions.apikey WithToken
//  @in                         header
//  @name                       Authorization
//  @description                请设置API的token, 注意是 “Bearer ”开头
{
        "securitySchemes": {
            "": {
                "description": "请设置API的token, 注意是 “Bearer ”开头",
                "in": "header",
                "name": "Authorization",
                "type": "apiKey"
            }
        }
}

good (dont use swag fmt, work)

// @securityDefinitions.apikey WithToken
// @in header
// @name Authorization
// @description 请设置API的token, 注意是 “Bearer ”开头
{
        "securitySchemes": {
            "WithToken": {
                "description": "请设置API的token, 注意是 “Bearer ”开头",
                "in": "header",
                "name": "Authorization",
                "type": "apiKey"
            }
        }
}
xieziheng1 commented 1 year ago

duplicated #1149

marktheunissen commented 9 months ago

We are also experiencing this.

I don't think #1149 is a duplicate, this issue happens for us too and it's easy to reproduce using soonio's example above. Once you use swag fmt, it breaks the parsing of the security definition and we get an empty string for the name

Solution is to leave it unformatted for now.

stivens13 commented 3 weeks ago

Getting the same problem. Is there a right way to define docs in order to generate correct OpenAPI securitySchemes with swag?