Description for API Key Security Definition.

[pomaretta]

Is your feature request related to a problem? Please describe.
I have a Bearer API Key security definition, due to Swagger 2.0, the user have to type "Bearer TOKEN" into the Authorize option.

Describe the solution you'd like
On the security definition of the API Key, define a description for it.

// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization
// @description "Type 'Bearer TOKEN' to correctly set the API Key"

Describe alternatives you've considered
This cannot be set through the generation. Maybe changing the docs.go to get this feature.

Additional context
I know the tag "// @description" will conflict with the Swagger API description, maybe with "@securityDefinitions.apiKey.description" can solve this conflict.

[ubogdan]

I was wondering how this is supposed to work when apiKey authentication doesn't support description.

[pomaretta]

I used a description tag inside a API Key definition on a production swagger files. For showing a tip when typing the API Token on the input text field.

"securityDefinitions": {
        "Bearer": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header",
            "description": "Type \"Bearer \" and then your API Token"
        }
    }

[pomaretta]

I read on the OpenAPI 2.0 specification that on the security definitions are fixed fields, on you can define a description for the security definition, where the type and description applies for basic, apiKey and oauth2 authentication here specifies it.

[ubogdan]

@pomaretta Thanks for clarifying this. Please feel free to contribute with a PR regarding this matter.

[nxvinh222]

Can you show me your definition, I tried all day and but couldn't make this work

I used a description tag inside a API Key definition on a production swagger files. For showing a tip when typing the API Token on the input text field.

"securityDefinitions": {
        "Bearer": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header",
            "description": "Type \"Bearer \" and then your API Token"
        }
    }

[pomaretta]

Hi @nxvinh222, simply adding this to your swagger, ensure that if you are using swag init to generate doc files, write this definition on the docs.go, on the document variable, otherwise you are setting up this definition on the .json or .yaml that doesn't apply to the final result.

"securityDefinitions": {
        "Bearer": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header",
            "description": "Type \"Bearer\" followed by a space and JWT token."
        }
    }

[daqiancode]

Here I use iris web server as example:
`
// @securitydefinitions.oauth2.password OAuth2Password
// @tokenUrl /api/iam/token
func main() {
app := iris.New()
if env.GetenvBool("app.dev", false) {
fmt.Println("Swagger doc reference https://github.com/swaggo/swag")
fmt.Printf("swagger doc: http://localhost:%s/swagger/index.html\n", env.Getenv("app.listen", "8080"))
// app.Get("/swagger/{swaggerPath:path}", irisSwagger.WrapHandler(swaggerFiles.Handler))

app.HandleDir("/swagger", iris.Dir("swagger"))
app.HandleDir("/docs", iris.Dir("docs"))

}
}`

add swagger/index.html
`

<title>SwaggerUI</title>

<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script> <script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-standalone-preset.js" crossorigin></script> <script> window.onload = () => { window.ui = SwaggerUIBundle({ url: '/docs/swagger.json', dom_id: '#swagger-ui', presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], layout: "StandaloneLayout", persistAuthorization: true, requestInterceptor: (req) => { if (localStorage.authorized) { var auth = JSON.parse(localStorage.authorized) if (auth.OAuth2Password && auth.OAuth2Password.token) { req.headers.Authorization = "Bearer " + auth.OAuth2Password.token.access_token; } } return req; }, });

    };
</script>

`

Reference: https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md
No need "github.com/swaggo/files"

After login

[JohnSalazar]

Hi, for OpenAPI 2.0 just enter the following comments and generate the docs by swag init.

1. To your main.go:

// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization
// @description Type "Bearer" followed by a space and JWT token.

2. To your handler/controllers that need authentication

// Profile godoc
// @Summary      Profile user
// @Description  get user info
// @Tags         users
// @Accept       json
// @Produce      json
// @Success      200  {object}  dtos.User
// @Failure      400  {object}  httputil.ResponseError
// @Failure      401  {object}  httputil.ResponseError
// @Failure      403  {object}  httputil.ResponseError
// @Router       /profile [get]
// @Security Bearer  <-----------------------------------------add this in all controllers that need authentication
func (auth *AuthController) Profile(c *gin.Context) {...}

On Swagger UI in a browser, you must specify the bearer in the value field of the authorization pop up:

[jgimenez]

// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization
// @description Type "Bearer" followed by a space and JWT token.

This doesn't work, because the @description is understood to be of the top level info object.

[matm]

Thanks @JohnSalazar, works perfectly, even with a global @description for the API.